Add a project

Every project lives in its own folder under src/content/docs/projects/. Adding one is three steps and takes about two minutes.

1. Copy the template

cp -r templates/project-docs src/content/docs/projects/my-project

Use the project’s real name, lowercased and hyphenated — it becomes the URL: src/content/docs/projects/my-project/ is served at /projects/my-project/.

Note

The template lives in templates/ at the repo root, outside src/content/, so it is never turned into a page. Don’t edit it in place — copy it.

Astro only excludes content files whose name starts with _; an underscore on a directory does not exclude the pages inside it. That is why the template sits outside the content folder rather than in _template/.

2. Register it in the sidebar

Open astro.config.mjs and add a block to the sidebar array, below the Projects comment:

astro.config.mjs

sidebar: [
  {
    label: 'Start here',
    items: [/* … */],
  },
  {
    label: 'my-project',
    collapsed: true,
    items: [{ autogenerate: { directory: 'projects/my-project' } }],
  },
],

Starlight 0.39 changed this shape

A group can no longer carry autogenerate directly beside its label — the autogenerate config has to sit inside items, as above. The old spelling fails the build with “Support for autogenerated sidebar groups was removed”.

autogenerate builds the project’s nav from the files on disk, so you never have to touch the config again as you add pages. Ordering inside the group comes from each page’s sidebar.order frontmatter, falling back to alphabetical.

3. Link it from the home page

In src/content/docs/index.mdx, replace the placeholder card with a real one:

src/content/docs/index.mdx

<CardGrid>
  <LinkCard
    title="my-project"
    href="/projects/my-project/"
    description="One line on what it does and who it's for."
  />
</CardGrid>

4. Check your work

npm run dev

Then visit http://localhost:4321. Before pushing, run the real build — it fails on broken internal links, which catches most mistakes:

npm run build

Where to put images

Put them next to the page that uses them, or in src/assets/ for anything shared. Reference them with a relative path and Astro will optimise and hash them:

![Topology of the test network](./topology.png)

Files in public/ are copied verbatim without optimisation — use that only for things that need a stable URL, like a PDF you link to from elsewhere.

Pulling docs from another repository

If you’d rather keep a project’s docs next to its code, add that repo as a submodule and symlink it in:

git submodule add https://github.com/you/my-project vendor/my-project
ln -s ../../../../vendor/my-project/docs src/content/docs/projects/my-project

Keep the frontmatter conventions the same in the upstream repo, and remember to run git submodule update --remote before building. This is more machinery than it sounds — only reach for it once editing docs in this repo starts to feel like the wrong place.