Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ability to configure the depth of a page context menu #598

Closed
patricklafrance opened this issue Aug 9, 2023 · 15 comments
Closed

Ability to configure the depth of a page context menu #598

patricklafrance opened this issue Aug 9, 2023 · 15 comments
Assignees
Labels
feature sponsored Sponsored issue to fast-track implementation
Milestone

Comments

@patricklafrance
Copy link

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

Special thanks to @patricklafrance for sponsoring this feature development.

@patricklafrance
Copy link
Author

Thank you very much!

@geoffreymcgill geoffreymcgill added the sponsored Sponsored issue to fast-track implementation label Sep 10, 2023
@geoffreymcgill
Copy link
Contributor

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

@patricklafrance
Copy link
Author

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

@patricklafrance
Copy link
Author

patricklafrance commented Sep 27, 2023

@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:

image

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:

image

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
Copy link
Contributor

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
Copy link
Author

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
Copy link
Contributor

geoffreymcgill commented Sep 27, 2023

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
Copy link
Author

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
Copy link
Author

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
Copy link
Author

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

depth

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
Copy link
Contributor

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
Copy link
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature sponsored Sponsored issue to fast-track implementation
Projects
None yet
Development

No branches or pull requests

2 participants