Starlight

Overview (reference)

It’s a documentation theme built on Astro. It should “just work” with Obsidian notes as long as you use the Starlight Obsidian plugin.

Quick reference

Updating Starlight: pnpx @astrojs/upgrade
Running in development: pnpm run dev
- Running with search: pnpm run build → pnpm run preview
My own personal publish flow:
- cd <Starlight repo>
- pnpm build
- git diff (just to check quickly that there’s nothing private)
- git add .
- git status (just one last check to make sure everything looks good)
- git commit -m "Publish notes"
- git push

Usage with Obsidian

If you’re only going to use Starlight for Obsidian and nothing else, then you can follow HiDeoo’s instructions. They essentially just boil down to the following:

Go through the official instructions for the Starlight Obsidian plugin.
Make sure your package.json file doesn’t have astro check.

Colors/themes

Use this tool. Make sure not to have DarkReader enabled since it will live-edit the site.

Troubleshooting

Folders with the same name as notes

This isn’t really a bug. For example, if I have this directory structure:

Cloud
- AWS
  - AWS
    - EC2
    - ECS
    - ELB
- AWS.md

…it’ll render like this: 200 HiDeoo said this:

Yes, this one is expected when a file and a folder at the same level have the same name. It would be weird to have a file named AWS and a folder named AWS in your sidebar and solutions handling this by having different behavior depending if you click on the name or the arrow of a folder is not something really accessible/recommended.