Ability to configure the depth of a page context menu

[patricklafrance]

For some pages, I would like to restrict the depth of a page context menu to h2 only. That would be useful if it was configurable with a page options.

[geoffreymcgill]

Thanks for the feature request.

Related to #440

This is a feature we have been contemplating for a while. I find your scenario of wanting to restrict to only H2 headings more valuable than enabling H4+ to be added to the table of contents.

If/when we implement this functionality, we would allow the heading depth to be fully configurable.

[geoffreymcgill]

This new toc feature has been included in the Retype v3.4.0 release.

This feature is a Retype Pro only feature.

New options include the Table of Contents label and depth.

The label is the string used at the top of the ToC column.

The depth configures which Headings to include in the generated ToC.

Samples

Project toc config sample:

toc:
  label: On this page # default from .resx, "Contents" for EN
  depth: 2 # default is 2-3

Page toc config sample:

---
toc:
  label: On this page # default from .resx, "Contents" for EN
  depth: 2 # default is 2-3
---
# Sample

Configuring the toc at the Page level overrides any Project level settings.

Acceptable values for depth include:

Value	Description
2	Include H2 headings only
2-3	default Include H2 to H3 headings
1-4	Include H1 to H3 headings
2,3	Include H2 and H3 headings
2,4	Include H2 and H4 headings
1,3-4	Include H1 and H3 to H4 headings, skip H2
1,2,3,4	Include H1, H2, H3, and H4 headings

Hope this helps.

[geoffreymcgill]

Special thanks to @patricklafrance for sponsoring this feature development.

[patricklafrance]

Thank you very much!

[geoffreymcgill]

Hi @patricklafrance, is the new depth setting working well for you? Does this fulfill your requirements?

[patricklafrance]

@geoffreymcgill 💯 using it for multiple pages and I love it 🙏🏻

[patricklafrance]

@geoffreymcgill I noticed that if a default page (default.md) has a custom depth, it's sub-pages will inherit from that depth. Is it the intended behavior?

For example, my retype.yml has the following configuration:

toc:
    depth: 2

For the following pages structure:

docs
    eslint
        default.md
        setup-polyrepo.md

Without any additional configuration, only h2 will be included in the ToC for the eslint/setup-polyrepo.md page:

If I configure the depth for eslint/default.md to include h2 and h3:

---
toc:
    depth: 2-3
---

Then the eslint/setup-polyrepo.md page now also includes h2 and h3:

My expectation would be for the eslint/setup-polyrepo.md page to still only include h2 in the ToC since this is the per project configuration.

Thank you,

Patrick

[geoffreymcgill]

it's sub-pages will inherit from that depth. Is it the intended behavior?

Yes, but we are reviewing this. There are some page settings, such as visibility and layout, that propagate to child pages when set on the folder root default page.

Thanks for letting us know about this scenario.

[patricklafrance]

I might be going a bit too far and maybe it's more of a documentation architecture issue than a Retype issue but for some of my pages, I would like to be able to control if a specific header should be included or not in the ToC.

Let me you know what you think!

[geoffreymcgill]

for some of my pages, I would like to be able to control if a specific header should be included or not in the ToC.

Can you elaborate on this statement?

In your original scenario, you can set depth: 2 on the eslint/setup-polyrepo.md to override the new folder default of depth: 2-3 that was set in eslint/default.md. Although with the current page config propagation rules, depth: 2 would also need to be set on all sub-pages of that folder if only only wanted depth: 2-3 on the parent default.md and depth: 2 on the children.

[patricklafrance]

Sorry, I wasn't clear, I switched to a completely different scenario.

Let's say there is another "custom-config.md" page that has been added to the previous pages structure:

docs
    eslint
        default.md
        setup-polyrepo.md
        custom-config.md

This custom-config.md page as depth: 2-3 to include h2 and h3 in the ToC:

---
toc:
    depth: 2-3
---

For the custom-config.md page, I want most of the h3 to be included in the ToC, but there are a few specific h3, that I would like to manually exclude from the ToC.

Again, maybe I am going to far and this is my documentation information architecture that should be revisited. Still I am wondering what you think about this scenario?

Thank you,

Patrick

[patricklafrance]

Follow up to my previous comment. instead of excluding specific headers, including only specific headers in addition to the ones that are included by default with the depth setting could also be a valid alternative.

[patricklafrance]

To provide a super concrete example. Given the following ToC:

I configured this page with a depth: 2-3 because I want the h3 for the "Block 2" but I would preferably not include the h3 for the "Block 1" and "Block 3".

[geoffreymcgill]

Still I am wondering what you think about this scenario?

I don't have a super strong opinion on this one, although my bias is to not include this functionality. I'm not seeing an advantage with excluding specific headings from the ToC. You are kinda messing unnecessarily with the consistency of the user-experience.

We do have an internal open feature request to add support for applying a {.plain} class to components such as images and links that would render those as raw <img> and <a> HTML elements, without any wrapping Retype elements. For example, adding ![](/static/sample.jpg){.plain} would render a plain <img src="/static/sample.jpg"> element without the wrapping <figure> that is added by Retype.

We could include {.plain} support on Headings, which would render as a plain <h3> element. A Heading with {.plain} would still be styled the same as the other Headings without {.plain}, but not include the hover # anchor link and could be excluded from the ToC. The following sample demonstrates two techniques for how the {.plain} class could be applied:

### environmentVariables {.plain}

or,

{.plain}
### environmentVariables

Let me know what you think.

[patricklafrance]

We could include {.plain} support on Headings, which would render as a plain

element. A Heading with {.plain} would still be styled the same as the other Headings without {.plain}, but not include the hover # anchor link

The reason I am adding those headers that I would like to exclude is strictly to get an # anchor link to facilitate sharing a link to a direct section of the documentation.