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 → git commit -am "Update Astro"
  • This upgrades Astro and Starlight, but not community plugins, so if you hit an issue, try pnpm update starlight-obsidian@latest.
• 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
  • Then, my Vercel account with adam@adamlearns.live will pick it up.
    • The only time I’ve seen this fail in normal usage is when Node needed to be updated, in which case I just changed the version in the “Build and Deployment” section.

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: 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.