Installation
From zero to a running local copy.
Prerequisites
| Tool | Version |
|---|---|
| Node.js | 18.20.8, ^20.3.0, or >=22.0.0 — Astro 5's supported range. Node 22 LTS is what the Cloudflare build uses; odd-numbered releases aren't supported. |
| npm | >=9.6.5, ships with Node |
| git | any |
| Obsidian | optional — the vault is plain markdown, so any editor works |
1. Start your own repository
Click Use this template → Create a new repository on the repo page. Choose Private if your notes are private; the published site is gated separately. Then clone it:
git clone https://github.com/<you>/<your-repo>.git
cd <your-repo>
You get a clean repo with a single initial commit and no upstream history — which is what you want for something you'll be committing personal notes into.
Fork instead only if you plan to send fixes back upstream; GitHub won't create a private fork of a public repo. Or clone the template directly for a local trial with npm create astro@latest -- --template treverehrfurth/astro-publish.
2. Install dependencies
npm install
node_modules/ is gitignored, so every fresh clone needs this once. Until you run it, every npm script fails with 'astro' is not recognized — that means dependencies are missing, not that the repo is broken.
3. Run it
| Command | What it does |
|---|---|
npm run dev |
Dev server with hot reload at http://localhost:4321/ |
npm run build |
Static build into dist/, then the search index |
npm run preview |
Serves the built dist/ — the closest local match to production |
Two differences from production are worth knowing up front:
- Search is empty in dev. The index is built after the site is, so it doesn't exist under
npm run dev. Usenpm run build && npm run previewto try it. - Vault edits need a restart. The loader reads the vault once at startup and caches it for the life of the process. Hot reload covers
src/, notcontent/.
4. Point it at your vault
The content/ folder is the vault. Either replace it in place:
rm -rf content/*
cp -r /path/to/YourVault/* content/
Open content/ directly in Obsidian and edit normally — commit and push to publish.
Or keep the vault outside the repo by copying .env.schema to .env and pointing at it:
OBSIDIAN_VAULT_DIR=../MyObsidianVault
That only works for local builds, since a CI build can only see files that are in the repo.
Next: Configuration.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
'astro' is not recognized |
node_modules/ missing |
npm install |
Unsupported engine warning |
Unsupported Node version | Install Node 22 LTS |
Port 4321 is in use |
Another dev server running | Astro falls back to 4322 — read the URL it prints |
| Search finds nothing | Index only exists after a build | npm run build && npm run preview |
| An edit to a note doesn't show up | Loader reads the vault once at startup | Restart npm run dev |
| Stale output after an upgrade | Cached build artifacts | rm -rf .astro dist node_modules && npm ci |
| A note is missing from the site | draft: true or publish: false |
See [[notes/getting-started |