fix(mdx-loader): the table-of-contents should display toc/headings of imported MDX partials

[anatolykopyl]

Pre-flight checklist

• [x] I have read the Contributing Guidelines on pull requests.
• [x] If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• [ ] If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This PR adapts the fix to ToC generation from https://github.com/shuding/nextra/pull/2199 to the toc remark plugin in docusaurus.

Test Plan

Now the title from _pagePartial.mdx is visible in the ToC of the /tests/pages page.

Also I've added a /tests/pages/partials-tests page for further demonstration.

Test links

Deploy preview: https://deploy-preview-9684--docusaurus-2.netlify.app/

Affected test page: https://deploy-preview-9684--docusaurus-2.netlify.app/tests/pages

New test page: https://deploy-preview-9684--docusaurus-2.netlify.app/tests/pages/partials-tests

Related issues/PRs

fix https://github.com/facebook/docusaurus/issues/3915

[netlify[bot]]

✅ [V2]

Name	Link
🔨 Latest commit	3d43631ba2072f031face572e5fbbe36580b3980
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65aab464a3d8d3000833330f
😎 Deploy Preview	https://deploy-preview-9684--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions[bot]]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 83	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/installation	🟠 89	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/category/getting-started	🟠 76	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog	🟠 70	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 63	🟢 97	🟢 100	🟢 100	🟠 89	Report
/blog/tags/release	🟠 69	🟢 100	🟢 100	🟠 80	🟠 89	Report
/blog/tags	🟠 77	🟢 100	🟢 100	🟢 90	🟠 89	Report

[anatolykopyl]

I consider this PR done. @slorber, could you please check it out? Any tips regarding how this can be improved are appreciated! I'd be glad to make changes to this PR if necessary.

[anatolykopyl]

Thanks for the detailed feedback! I'll be working on improving this PR in the following weeks.

[anatolykopyl]

Moved the dogfooding into _docs tests. Added a deeply nested partial and a partial with props in the heading. Last one is not working, the heading shows the text passed to the prop as expected, but the ToC displays just the text props.propname. Quite interesting, no idea how this can possibly be fixed.

Also since I changed the plugin to not generate any js anymore, only ASTs, the existing unit tests for the ToC plugin became useless, as they checked generated mdx. I changed the unit tests to output ASTs, so the work of the plugin is visible.

[slorber]

Thanks @anatolykopyl , looks like it's working nicely.

Almost ready, I'm just going to refactor some details and merge asap!

[slorber]

Thanks for your initial port @anatolykopyl, now it's ready to merge 🎉

---

Thanks for the Nextra inspired solution @dimaMachina

FYI a little detail in your implementation that does not work is when the import is after the usage. Probably not a big deal, but I fixed it in this PR:

<Partial/>

import Partial from "partial";

That would be interesting to see if we could find a shared abstraction that benefit to Docusaurus, Nextra and others, but not sure it's possible atm considering the little differences here and there: we probably need to chat and design the whole thing.

[argos-ci[bot]]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	🧿 Changes detected (Review)	7 changes	Jan 19, 2024, 5:50 PM