feat(v2): allow specifying max depth for TOC #4310
Conversation
|
[V1] Deploy preview success Built with commit 2869379 |
|
Size Change: -25 B (0%) Total Size: 532 kB
ℹ️ View Unchanged
|
|
Deploy preview for docusaurus-2 ready! Built with commit 2869379 |
lex111
force-pushed
the
lex111/iss2700
branch
from
e2b2465
to
2869379
Compare
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-4310--docusaurus-2.netlify.app/classic/ |
There was a problem hiding this comment.
Not very satisfied with this solution, as it complicates the remark loader and I see a better way:
- let the remark plugin computes the TOC with infinite length
- handle the max depth at render time directly in the theme
This has advantages:
- simpler to implement and maintain
- no need to configure anything on the site
- depth for right TOC can be controlled by md frontmatter
- depth for inline TOC in MDX can be controlled by prop
- we can just use maxDepth=2 as default prop to the TOC theme component
- a theme config can set-up the default TOC depth for the whole site (not just the docs plugin)
|
I don't quite understand you, we normalize headings (make proper list structure) as it is now, but handle all levels in the loader itself without any options, right? |
Not sure what you mean. Currently, we handle the max depth of the TOC at the mdx loader level, but I think we should not and let the mdx loader compute full TOC without any limit, and apply the max depth limit in the theme instead |
|
In short, I remove code related with configuration. This way the final structure of TOC tree will still be generated in the loader (see the "toc plugin maximum deeply headings" test for example) . And after in TOC component we will only render the appropriate level by filtering initial result, in accordance with the frontmatter settings or defaults. Right? |
|
exactly :) |
| @@ -44,28 +40,57 @@ function search(node) { | |||
| const onHeading = (child, index, parent) => { | |||
| const value = toString(child); | |||
|
|
|||
| if (parent !== node || !value || child.depth > 3 || child.depth < 2) { | |||
| if ( | |||
| parent !== headingNode || | |||
There was a problem hiding this comment.
Is it possible (either as part of this PR or a future one) to add a config option to remove this part of the conditional?
I have a use case where I want headings that aren't at the root of the document (in this case, inside a list element) to show in the TOC.
There was a problem hiding this comment.
Can you explain better your use-case with an example source doc and an example TOC we should compute? (ie provide a test case somehow?)
If we use TOC min/max heading levels for a whole doc, does it work for your use-case? (like min=3, max=4 for example?)
CF #5578
There was a problem hiding this comment.
The TOC I would like is:
- Purposes
- Policies and party strategy
- Public office
- Decision-making
- Openness
- Affirmative action
Without the suggested change (which I am implementing in the form of a patch), I get no TOC at all, because all the headings are not top-level elements.
There was a problem hiding this comment.
I'm not really able to run your doc, can I see a live published version of it too?
What I understand is that you still want min=2 for the toc headings, but you need headings that are part of a list?
Purposes
This is not really an use-case we had in mind afaik. Why can't your readings be top-level and are part of the list?
Is this the intended behavior?
Can you explain your motivations for this unusual headings usage?
There was a problem hiding this comment.
The published version is at https://australiangreens.github.io/agvrules/proposed-constitution/fundamental-matters/
The headings are part of the list item because:
- that's how they appear in the source document I'm copying
- that's semantically correct
- that structure means that things that parse lists read it correctly
But I think there's also much simpler situations where a heading might not appear at the root of a document. For example, if it's inside a quote block or an admonition. And I can see cases where people would want those to show in the TOC.
My point was these usecases would be very easy to accommodate with an extra config option.
There was a problem hiding this comment.
Thanks @ineffyble
As the TOC PR is already complex enough, I'd like to support your use-case in another one
Can you please open another dedicated issue with all those relevant info?
For example, if it's inside a quote block or an admonition.
I'd find this weird to use a heading this way 😅
And I can see cases where people would want those to show in the TOC.
I'd be very interested to have a list of use-cases that you have in mind where the current logic is not good enough.
Passing a function as TOC config is the most flexible, but it may not be an ideal API to deal with and would be hard to document, so I'm not sure this is what we want. If we supported your use-cases by default it could be good enough?
|
👋 Hi there, I'm interested in having this feature in my Docusaurus website and have started working on implementing the change described by @slorber in #4310 (review)
See #5578 |
|
Closing in favor of #5578. |
Motivation
Trying to finally fix #2700.
This PR also introduces the ability to override options for the our own custom Remark plugins (see config file). Perhaps this will come in handy in #4222 to make custom headings ids configurable.
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
Related PRs
(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)