ToC: links to markdown headings

[wojpawlik]

Search Terms

table of contents, markdown heading links

Problem

In https://github.com/telegraf/telegraf/issues/1308#issuecomment-765118432, some people complained that new typedoc-generated docs are more difficult to navigate than the old ones generated with docute@3. They didn't specify why.

Suggested Solution

In the sidebar of files rendered from markdown, in addition to API reference links, display ToC consisting of links to markdown headings, like docute@3 (https://telegraf.js.org/v3, https://telegrafjs.org/) and docsify@4 (https://v3.telegrafjs.org/).

[Gerrit0]

Including markdown headers in the navigation seems like a good idea to me. The existing theme architecture really isn't set up to do this easily, but I think I should be able to address this when reworking the themes in 0.21.

---

Wow, very hard to work with feedback like what you received!

I took a look at both docs, and I think the main issues are:

1. The custom theme you're using doesn't include search.js in default.hbs, so searching is broken

2. The doc comments are not as comprehensive as the previous API reference - for example, the Telegraf constructor:

   The old docs immediately show what you can provide to the constructor

   The new docs don't include that information, users can't easily click on Options and see what is expected.

[mristin]

@Gerrit0 I don't know if you plan to work more on this issue. Here is just some feedback from our side. Please apologize if I misunderstood this feature, and please let me know where else I should move my comment.

We pack all the information like "getting started" and "contributing guide" into one big readme file. We decided not to use plugins such as @knodes/typedoc-plugin-pages as we couldn't really tell for how long in the future they are going to be maintained.

So far this works for us, but it is very difficult for the readers to follow the text as there is not table of contents on the right. If a reader wants to jump to a section or sub-section of the readme, s/he has to scroll all over to the top, which can be tedious for such a long text file.

Our project is still work in progress, but you can have a look at this commit: https://github.com/aas-core-works/aas-core3.0rc02-typescript/tree/b546e7c91dc3a69be334cb7146d8876388936468

Please let me know if I can help with the implementation somehow. I believe such a feature would be generally useful to all the users of TypeDoc, and hence would suggest to implement it in the core rather than as a separate plugin.