Comments (14)
For a quick and hacky solution you can nest the docs
collection within a second docs
folder like src/content/docs/docs
to prefix all starlight paths with /docs
from starlight.
Unfortunately configuring the href
of the site title is not currently possible but you can use a client side script to correct the href
when the page loads, something like this:
starlight({
head: [
{
tag: 'script',
content: `window.addEventListener('load', () => document.querySelector('.site-title').href += 'docs/')`,
},
],
});
from starlight.
Hey @jagu-sayan! As noted above this is already supported, we’d just like to improve the DX around it.
Thanks for sharing your other ideas — things in this direction are all stuff on our radar 🙌
from starlight.
Thanks for the workaround.
from starlight.
It's a must have for me :)
Like it's done by QuestDB website build with Docusauru (Look code).
Suggestion to add more powerful customization:
- possibility to customize header and footer section of Starlight
- possibility to use the same layout for all the website (main, blog and documentation)
- possibility to implement our own layout with an option
useCustomLayout: true
- export components (like Search.astro, SiteTitle.astro, ...) used by header and footer to use them in our custom layout
from starlight.
Hi @delucis, thanks for your response. I agree with your approach to have the base
option.
// astro.config.mjs
defineConfig({
integrations: [
starlight({
title: 'Docs at a subpath',
base: 'guides',
}),
],
});
Here are my suggestions:
- By default, Starlight's site-title link should point to
/${base}/
but make it configurable. So, if someone wants the docs link to point to/
or/random-link
they are free to do so. In that case, the config would look like this:
// astro.config.mjs
defineConfig({
integrations: [
starlight({
title: 'Docs at a subpath',
title-link: '/'
base: 'guides',
}),
],
});
- Regarding the 404 (not found) page, it seems weird to have the docs at
/guides
but render this page at/404
. Mainly because of the Starlight's styling/layout, and also because of main Astro site's404
page. To me/guides/404
seems a more suitable option, however I don't fully understand why this wouldn't be picked up by static hosts.
from starlight.
Thanks for the quick solution. Seems to work alright, although I can't find a way to update the nav link in the header. It still points to the root url.
from starlight.
Thanks for the issue @mirrorleap! As @BryceRussell said, this workaround is available today and I just wrote some docs for this approach, but we would like to improve support here in the future.
I think most likely would be something like a base
option:
// astro.config.mjs
defineConfig({
integrations: [
starlight({
title: 'Docs at a subpath',
base: 'guides',
}),
],
});
This would prefix all Starlight routes with /guides/
, so that e.g. src/content/docs/index.md
is available at /guides/
instead of /
.
There are some questions around this still to answer:
-
Should Starlight’s 404 page also inject at
/guides/404
? This wouldn’t be picked up by most static hosts, but may be what’s expected when doing this as you presumably have other routes. -
What should happen to the Starlight site title link? As you noted, it currently will link to
/
(or/lang/
potentially for multilingual sites). I can imagine people wanting both/
or/${base}/
in this case depending on their preference so may need to make this configurable. (As an example, https://terrateam.io/ includes Starlight on/docs
and linking back to the home page feels right there.)
from starlight.
I don't fully understand why this wouldn't be picked up by static hosts.
Hosts like Netlify, Vercel, and GitHub Pages have a very simple default behaviour where they look for a 404.html
file in the root of the pages to deploy and serve it as the 404 page for any route they don’t find. That means they ignore any 404 files nested in a subdirectory. This is configurable — for example in the Starlight docs we tell Netlify to use /es/404
for 404s starting with /es/
, /fr/404/
for 404s starting with /fr/
etc. — but would require some user config.
That said, if a user’s project already creates a root-level 404, then Starlight’s shouldn’t overwrite it.
from starlight.
Making a note that it might not be super clear what happens to base
and language tags in URLs.
Which of these should the pattern be?
/lang/base/
(e.g./fr/docs/
)/base/lang/
(e.g./docs/fr/
)
Usually language tags are the first segment in a URL path, but not sure if that’s what everyone looking for base
support expects or not.
This wouldn’t impact base
usage for monolingual sites though.
from starlight.
Just came across an issue with starlight being incompatible with a custom 404 page. A base URL option would be great as I don't want to expose the documentation whenever a user enters a wrong URL in general.
from starlight.
@delucis as we have discussed in Discord, would like to get this issue! I have a branch as you can see in the historic of the issue. I figured out how to add baseUrl at the configs, but not the right entry point to make it work!
from starlight.
I'd personally put the language before the base path, but imho it should be a selectable option.
If you have a monolingual site, with multi-lingual docs, then after the base path makes sense, if everything is multilingual having the language path moved in the middle of the path makes no sense.
from starlight.
If there's multiple starlight sites in the same origin, should theme selection also be separated?
Currently starlight is using hardcoded starlight-theme
:
Example of separated theme selection implemented in mkdocs-material, they are prepending the base path to the key.
Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/
:
__md_scope=new URL(".",location)
__md_get=(e, _=localStorage, t=__md_scope) => JSON.parse(_.getItem(t.pathname+"."+e))
Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/getting-started/
:
__md_scope=new URL("..",location)
Excerpt of formatted source of https://squidfunk.github.io/mkdocs-material/blog/2023/10/02/sunsetting-gitter-towards-efficient-community-engagement/
:
__md_scope=new URL("../../../../..",location)
from starlight.
Related Issues (20)
- Pagefind doesn't work with a gitlab pages deployment and bun HOT 1
- Can't deploy on Cloudflare HOT 1
- config options are not followed in pagefind search
- CSS not displaying on pages other than homepage HOT 4
- Hot Updates Reporting Errors Causing Project Crashes HOT 1
- Throws on reading `import.meta.env.BASE_URL` in Deno environment HOT 10
- Pagefind not working with PNPM and Firebase Hosting HOT 4
- do something about empty autogenerated sidebar groups HOT 1
- Astro devToolBar audit create a warning on code block HOT 4
- font not rendered correctly on firefox
- Language Select incorrectly appends locale when switching index pages HOT 5
- Mobile header cannot accumulate long documentation name and it covers search button HOT 1
- Table of Contents Glitch HOT 3
- Both dark and light Starlight appears when JS disabled HOT 1
- Letters get auto-generated in front of Frontmatter when have closing HTML tag in Markdown. HOT 4
- Embed Microsoft Video Not Working on Safari HOT 3
- Search not working in Cloudflare workers HOT 4
- Failing to import night-owl-dark.jsonc?raw HOT 10
- Select options are not centrally aligned HOT 2
- UI text not translated when creating a multilingual site with only one locale HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from starlight.