Allow custom paths for content

[fea17e86]

What version of starlight are you using?

0.15.0

What is your idea?

Hi!

I would like other directories to be allowed as the root for starlight content. For example, instead of having the docs located in src, like:

src/
   content/
      docs/

I would like to have them in the root of my repository, like:

docs/
src/

The configuration should allow me to configure directories outside of the source directory to be scanned for content. This should also allow to separate the content from components.

Why is this feature necessary?

I love Markdown (and I believe it is the reason why it is so popular) for being (mostly) very well readable in the raw text form and obviously in the rendered HTML form. This is why I want to use it for my tech documentation.

It is just extremely helpful to be able to immediately find and read the documentation of a project, without being hidden in a src directory and somewhat mixed with components and such.

This would somewhat follow the philosophy behind progressive enhancement, in the way that you have access to a tidy, minimal, always readable documentation (Markdown) and only if you access the deployed starlight pages you access the improved UI and UX.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[mere]

+1 to @fea17e86's idea. I would like to use starlight in a monorepo, where it collates the docs from multiple packages.
Being able to change src/content/docs/ to a custom array of entry points (ideally using filter patterns) would be very useful.

[jorenbroekema]

Yeah I would also very much appreciate if I could put all my contents inside a docs folder into the root of my project, my project is a JS library and its source files already live in the src folder, I'd love it if I could keep docs and library source files in separate folders

[mere]

As a workaround, I symlinked the docs folder into the root, it worked well.

[delucis]

Just to link it here, this will hopefully be more easily solved by current work on Astro’s content collections system. For people who want to follow along with that work, there’s a roadmap discussion: withastro/roadmap#946

[yamcodes]

Are there any updates on this ?

[delucis]

Hey @yamcodes! We updated Starlight to support Astro v5 in our 0.30 release which in theory unlocks this. However, there are still a few blockers for us fully supporting custom docs locations. (Basically there are some places internally where we need to know the collection’s file path, and currently Astro does not offer an API for us to know the content collection configuration.)

Nonetheless, it does mostly work. Here’s an example with a docs/ directory directly in the project root instead of in src/content/docs/: https://stackblitz.com/edit/github-yvpchbvn?file=src%2Fcontent.config.ts

Off the top of my head, I think the features that aren’t fully supported when doing this are:

• Multilingual sites (mostly works but there are some bugs around remark plugins)
• Last-updated dates (relies on Git updated times for src/content/docs/ so doesn’t work with custom locations)
• Autogenerated sidebar groups also seem not to be working, but I think that should probably be fixable (and you could workaround that in the meantime by using other sidebar configuration approaches)

[moltar]

My use case is to document packages in a monorepo with this layout:

packages/*/README.md
packages/*/docs/*.md

Starlight is planned to live in:

apps/docs/

And I want to generate docs for each package and publish them as one site.

Is something like this possible already?

[delucis]

My caveats in my comment above would still apply, but if you were happy to write a custom Astro content loader for this, I think yes. Astro has its own glob() loader but this computes the slugs for things based on a common base, so I guess that probably would not work in your case because I guess packages/package-one/docs/something.md should not have a URL of /package-one/docs/something/ but maybe /package-one/something? And maybe you want to map README.md to something else, rather than a URL including /README? So given that custom mapping there’d be a bit of work.

Another option might be to symlink the files into /apps/docs/src/content/docs/ in the structure you desire, but I’ve had mixed success in the past with symlinking content like this, so I can’t promise that works.

[moltar]

Your first approach sounds good to me, I am not too snobby about URLs at this point, just want to make it work 😁

What about using generateId to override slugs?

https://github.com/withastro/astro/blob/817fe553899d0a8a0e4ff27c8d062bf1e24ca566/packages/astro/src/content/loaders/glob.ts#L32C2-L32C12

[delucis]

Ah yeah, I forgot about generateId! I would think that might work, yeah. Let us know how you get on.