← Wiki

From Obsidian to the site: the Astro template

  • 4 min read
On this page

The site is Astro’s official blog template, blog, which Astro itself offers when you create a project. It already comes with a list of posts, a post page with a cover image, an RSS feed and a sitemap. On this page you download it into the vault, connect its posts folder to your blog/ folder and see the result on your computer.

The commands run in the terminal (the Terminal app on macOS). Tested on macOS with Astro 7.

1. Check Node.js

The template requires Node.js 22.12 or later. Check which version you have:

node --version

If the command is not found or shows an older version, install the LTS version from nodejs.org.

2. Download the template into .site/

In the terminal, go to the vault folder and create the project:

cd "/path/to/My vault"
npm create astro@latest .site -- --template blog --install --no-git --yes

What each part does:

  • .site is the project folder. The dot at the start of the name hides it from Obsidian.
  • --template blog picks the blog template.
  • --install installs the dependencies.
  • --no-git skips creating a repository inside the vault, which already is one.
  • --yes accepts the default answers to the installer’s questions.

3. Connect the posts folder to blog/

The template reads posts from .site/src/content/blog/, which comes with five sample posts. Delete that folder and put a symbolic link to the vault’s blog/ folder in its place:

cd .site
rm -rf src/content/blog
ln -s ../../../blog src/content/blog

The path ../../../blog is relative to the link’s folder: it goes up out of content/, src/ and .site/, and reaches the root of the vault. Because it is relative, the link keeps working on another computer and on the automation’s machine, where the vault sits at a different path.

This is the only point of contact between the vault and the site. The template’s code does not change: it still reads src/content/blog/, and what it gets is your notes.

4. Name the site

In .site/src/consts.ts, change the site’s name and description:

export const SITE_TITLE = 'My blog';
export const SITE_DESCRIPTION = 'What I write in Obsidian.';

In .site/astro.config.mjs, set the site’s address, which the RSS feed and the sitemap use. If you don’t know it yet, leave it as is and come back after the Cloudflare page:

site: 'https://my-blog.your-account.workers.dev',

The template’s Home and About pages have sample text. Editing them (src/pages/index.astro and src/pages/about.astro) is optional and does not affect the blog.

5. Preview the site on your computer

Still inside .site:

npm run dev

Open http://localhost:4321/blog/ in your browser. The note you created in blog/ on the Obsidian page shows up in the list, as will every note you add to the folder, with its address taken from the file name. To stop, press Ctrl+C in the terminal.

To check exactly what the automation will do, build the full site:

npm run build

The output goes to .site/dist/, which is the folder sent to Cloudflare.

What the template refuses

The template defines the required properties of a post and checks every note before generating any page. If a note is wrong, npm run build stops, and so does the automation. In the tests for this guide, these were the messages (with the terminal formatting simplified):

A note with an empty description:

[InvalidContentEntryDataError] blog → vazio data does not match collection schema.
  description: Expected type "string", received "object"

A note with pubDate: tomorrow:

[InvalidContentEntryDataError] blog → ruim data does not match collection schema.
  pubDate: Expected type "date", received "object"

A note with an image that does not exist in images/:

[ImageNotFound] Could not find requested image `images/nao-existe.png`. Does it exist?

The first line gives the type of error and the note, identified by its address (blog → vazio is the note blog/vazio.md; the test notes had Portuguese names).

The template does not check links between notes: a link to another note in the vault goes to the site as is, and does not lead to that note’s page. To point to another post, use the site address (/blog/second-post/).

Push the vault

Push the vault with GitHub Desktop. The .site/ folder already comes with a .gitignore that leaves out the dependencies (node_modules/) and the built site (dist/). The symbolic link goes into the repository as a link, and that is how the automation finds it.