Vitepress: Customize generated sidebar

[gossi]

With the default settings for typedoc-plugin-markdown also the typedoc-vitepress-theme works very well.

It got me confused, that I then had the index.md (aka readme) and globals.md but only the globals.md was linked from the sidebar. So I turned on mergeReadme which gave me the output I was looking for (only the index.md file).

Unfortunately the vitepress sidebar generator didn't pick that one up and linked to the globals.md file, which then doesn't exist.

[gossi]

I think I run into some caching. Case closed, mystery stays 😂

[tgreyuk]

You could also just turn off the readme with --readme none and then manage the Readme separately to the generated docs.

[gossi]

My original problem is solved, yet want to share my initial thoughts on what I attempted to do:

The sidebar was generated for me. It had a good structure, I wanted to show the readme + the toc for the entire package (index or globals). The merge was fine for me to do that.

Instead a little fine-control could be what I was looking for, e.g. have the package name link to the readme or the index/globals (if that's configurable). Or to have two separate packages one for the index, one for the readme - but both in the sidebar.

I'm not firm with typedoc and if that's straight generatable from there and the vitepress integration is able to pick it up (then shame on me for not looking into that). Yet probably there is a little more control over the generated sidebar 👍

[tgreyuk]

Thanks for this. I have updated so the nav links point to readme (if present). As we already have the navigation I think linking to the additional index page is superfluous in this instance. Package name in the breadcrumbs also link to the readme.

I assume this is the kind of behaviour you had in mind but if you think some additional config is required let me know.

Have tested it out on your repo.

Fix versions

"typedoc-plugin-markdown": "4.0.0-next.42",
"typedoc-vitepress-theme": "^1.0.0-next.7",

Demo

[gossi]

Oh cool. Removing mergeReadme to come up with this result is really cool, as it works for me, because I also wrote the readme accordingly.

It might even be a good default. However, for some readmes that merger might give awkward results (especially when the readme is very long, but then they wouldn't use vitepress or similar - hmm 🤔). But that's already premature optimization land, as there will be issues for that ;)

One thing: the sidebar links to @theemo/build/index, whereas I think @theemo/build/ should be enough?

Related: I personally prefer links not to have a trailing slash - In that case here, it actually leads to a 404 (but I think this is more of a vitepress thingy).

[tgreyuk]

One thing: the sidebar links to @theemo/build/index, whereas I think @theemo/build/ should be enough?

I'll take a look.

Related: I personally prefer links not to have a trailing slash - In that case here, it actually leads to a 404 (but I think this is more of a vitepress thingy).

Yes i noticed that too (and I agree with your premise) but as you say it creates 404 without (but haven't really looked into it yet).

[gossi]

Correction, the link goes to: /api/@theemo/build/index.md and vitepress renders it as /api/@theemo/build/index

[tgreyuk]

Paths are updated without "index" in versions:

"typedoc-plugin-markdown": "^4.0.0-next.45",
"typedoc-vitepress-theme": "^1.0.0-next.8",