Page TOC not showing up

[juandiegopalomino]

I'm trying to use docsy for my project's documentation, but the right-hand side menu is not appearing (the one with the table of contents and "Edit this page" etc...). This looks very ugly and I don't know why it's not working.

[narrenfrei]

If I remember correctly without a computer to check, the Repository links have to be enabled or the content of the page must have enough headlines, otherwise there is no right sidebar built.

So try to set more headlines in your content markdown file or/and check if the repository links are enabled.

[LisaFC]

That is very weird. Agree with @narrenfrei, can you check that you're using regular Markdown/HTML headers for your section titles, as that's what the right nav is built from.

[polarweasel]

It's weird indeed, and really breaking a bunch of our pages, but it's coded into Docsy's TOC generation... If the generated HTML for that TOC is less than 200 characters, the TOC doesn't get output into the page.

What is the reasoning behind the 200-character minimum? (@narrenfrei and @LisaFC tagging you since this is old, but affecting my team as we try to deploy Docsy on a large docs site...)

https://github.com/google/docsy/blob/main/layouts/partials/toc.html#L3

[polarweasel]

Should have added: I've fixed this locally by overriding the toc.html shortcode, but this behaviour should get fixed in Docsy. I lowered the minimum to 100 for now.

[LisaFC]

Huh, that's extremely strange, and thanks for spotting it - I didn't create that TOC file and I'd never noticed the character minimum, it does indeed seem quite high given that people might have very short header titles. Would you create a PR to reduce the minimum to 100 in the theme version, please?

[raum51]

I've restructured the partial toc.html a while ago (with my old name @narrenfrei) and I also wondered about this limit but let it as it was before my updates. In my own productive Docsy, I have disabled this limit by overwrite the toc.html.

I would support to remove this limit or better make it configurable by parameter (with default value 200).

[polarweasel]

@raum51 I wonder what the logic behind the character count is, rather than a word count (or better, heading count)?

At Yugabyte, we're doing a variety of overrides with the TOC, but I'll ask the developer who's working on our site to take a look at this issue.

[mnordhaus]

Let me link my Idea here it is not similar, but related: #1093 IMHO it should be possible that the reader can navigate to the contents of the righthand sidebar even on a small screen like an iPhone. I am happy to hear your thoughts on that discussion item. I am currently experimenting with that Idea.

[LisaFC]

What do we think of @samiahmedsiddiqui's solution in #1110 (thanks for that!)? We'd need to document it as well obviously.

[chalin]

Related:

• parameter to customize the length of toc #326
• Pages with non-trivial but short TOCs don't get displayed open-telemetry/opentelemetry.io#712

Some thoughts on the subject:

• Character count of the TOC is not a sensible metric, so we shouldn't parameterize on that.
• In fact, I don't think that we should add any parameters at all. The default behavior should be the following (IMHO): show the TOC if and only if it is non-empty. If projects want to refine this behavior (by counting the number of TOC entries for example), they can override the template.

Thoughts?

[chalin]

• Proposed solution: Display non-empty page TOC #1147

[LisaFC]

Agreed! The only situation I can think of where you might not want to display the TOC would be if you had a page with only one heading or something and it looked a bit odd - but in that case we have a parameter to switch off the TOC, don't we?

[chalin]

The only situation I can think of where you might not want to display the TOC would be if you had a page with only one heading or something and it looked a bit odd

Right it sometimes looks odd, but I've seen cases (where the pages are particularly long), where it makes sense to keep the solo TOC entry.

but in that case we have a parameter to switch off the TOC, don't we?

Yes, the notoc page parameter. Though that doesn't seem to be documented. I'll create an issue for that. (Done, see #1150).