Vitepress: Make `basePath` configurable

[gossi]

Hej Hej,

I went experimental and trying the vitepress integration. I must say it is fantastic and I really like it, great job there 👏

One thing I noticed, is the basePath is not configurable and depends on your physical folder structure, rather than your documentation structure. That is the outDir is hardcoded for links here:

https://github.com/tgreyuk/typedoc-plugin-markdown/blob/4c6fe809ad7335316ca21ca8d032318965c45b32/packages/typedoc-vitepress-theme/src/index.ts#L49

If it shares the same purpose, then use basePath from typedoc itself - that at least my first go to. Alternatively, I'd expect this to be part of the vitepress options.

---

My workaround for now:

// package.json
{
  "scripts": {
    "api": "rm -rf docs/api/ && typedoc && mv api/ docs/"
  }
}

[tgreyuk]

Hi,

So just to clarify 100% what your issue is.

a) Currently it is assumed that TypeDoc is running off the VitePress root. So assuming you are running from the VitePress root you should just be able to just pass in the out option i.e.

typedoc --out ./docs/api

That should setup the paths correctly.

b) If you are not running TypeDoc from the VitePress root then we will need another option named something likevitepressRoot that defaults to ./. Should probably expose something like that anyway.

[gossi]

I'm sorry, my bad to not make this more clear. It is what you consider under option (b).

Here is my typedoc.json config: https://github.com/theemo-tokens/theemo/blob/ad8dfc66f0d61e0209e59ff0498492cd27b23f0e/typedoc.json

Also the repo at the time of writing: https://github.com/theemo-tokens/theemo/tree/ad8dfc66f0d61e0209e59ff0498492cd27b23f0e

• vitepress: docs/ - contains the docs + its config
• typedoc, run from the root with entryPointStrategy set to packages
• packages are located in packages/@theemo/*
• typedoc is run from the repo root and then placed under docs/api/ (see the workaround above - ideally would like to create it there)

Not sure if pointing to the root of vitepress is helpful, e.g. if this is two folders deep, would it work? So probably something along the lines of <base href=""> is the proper mental model?

[tgreyuk]

@gossi thanks.

I have been exploring a few options here. The issue is that the sidebar links need to be from the VitePress root and we have no context of this at the time of publishing. All other links are relative so there is no problem outside of the sidebar.

Solutions:

a) Attempted to resolve this programatically from exploring the file system for a folder named .vitepress. This works but feels a bit brittle.

b) Expose an additional option docsRoot that is the path to the VitePress project root which defaults to ./.

c) Expose a new option exposed to the sidebar sidebar.basePath which I think conceptually works best (its not published yet but just floating my idea):

Let me know if you think this makes sense.

[gossi]

I like that, sounds very good. Option (b) and (c) are both fine, no preference from my side.

[tgreyuk]

Went for docsRoot option in the end which is in "typedoc-vitepress-theme": "^1.0.0-next.7".

So you could just do the following and remove the mv script.

"out": "./docs/api",
"docsRoot": "./docs",

https://www.typedoc-plugin-markdown.org/themes/vitepress/options#docsroot

[maximesimoncelli]

Hello, had the same problem as @gossi, just tested the -next.7 release and it works perfectly, thanks !

[gossi]

Absolutely fantastic, I love it 👍 Thank you so much 🙇

Happily closing this one.