Astro Starlight for Docs-As-Code

Over the last couple of months, we’ve been working to implement a docs-as-code trial for an important modernization project. Docs-as-code lets us manage documentation in the same way as source code - version control, easier collaboration, and automated publishing. I chose Astro with the Starlight template because it’s simple to setup, fast, and works well for technical documentation. I switched my personal blog to astro recently and have been really pleased with the performance and workflow. Here’s how we got it working on our Windows 11 development machines leveraging symlinks.

Setting It Up

We setup our repos with a /src for all source code and /docs for all documentation, so the root of your repo should look like this:

/docs
/src

Next, install starlight into your repo. We use Windows 11 and Windows Terminal, so I needed to use a triple dash (---) to separate the command from the template parameter. The starlight documentation and many blogs only show a double dash.

npm create astro@latest --- --template starlight

Now test that the basic install is working as expected. Run the development server and connect to the site on the port on the console output.

cd starlight
npm run dev

This should run the starlight site, the URL will be printed on the screen. Open the site to confirm everything is working. Next, we’ll setup the symlinks to your docs folder. Since I use Windows Terminal and mklink is a cmd.exe call, we need to use the following commands. You’ll need to have Administrator access to do this.

cd src/starlight/src/content
rmdir docs
cmd /c 'mklink /d docs "..\..\..\..\docs"'

The symlink should now be created. You can view the results by running the following:

> cmd /c dir
...
2024-09-02  11:38 AM    <DIR>          .
2024-09-02  11:25 AM    <DIR>          ..
2024-09-02  09:23 AM               190 config.ts
2024-09-02  11:38 AM    <SYMLINKD>     docs [../../../../docs]
...

> cmd /c dir docs
...
2024-09-02  11:46 AM    <DIR>          .
2024-09-02  11:24 AM    <DIR>          ..
2024-09-02  11:46 AM                89 index.md
...

If you get an error on the dir docs command, your symlink isn’t working properly and needs to be corrected.

Getting Symbolic Links to Content Working

Cannot find module '@astrojs/starlight/components' imported from ...

The solution was to configure Vite to preserve symlinks, per the Unknown Content Collection Error when content directory is a symlink · Issue #9088 · withastro/astro · GitHub issue. There is another solution there involving a plugin, but I haven’t tried it nor do I know if it’s officially supported. We’re currently sticking to this approach.

export default defineConfig({
  vite: {
    resolve: {
      preserveSymlinks: true

    }
  },
  ...
});

Symlinks on Windows

1. Install the latest Git for Windows, select “Enable Symlinks” during the install process.

2. Open a terminal with Administrator access.

3. clone the repo. The administrator access will create the symlink properly. On subsequent pulls, commits, etc, you won’t need the Administrator level access. If you don’t have Administrator access or developer mode enabled, the clone will create a file with the path as it’s contents instead of the symlink.

Alternatively, you can enable developer mode to allow non-administrator user to create symlinks. I haven’t tried this yet. See the documentation for details and the procedure.

What’s Next

We use Elastic (and I love it!) for our observability. I wanted to add our docs to our observability platform because… why wouldn’t you! We instrument all of our applications and I want to understand the usage and performance of our docs too. My hopee is that this will let us track usage, identify problem areas, and measure the impact of improvements. More to come on that once we have it working.

So far, Starlight has been great for our docs-as-code workflow. It’s fast, simple, and integrates well with our branching and publishing processes. I’m looking forward to expanding this to more of our documentation!