Blogging with SiYuan and Astro

Today I want to show you all how you can leverage SiYuan as a Markdown editor to write blog posts, and publish them on your Astro website in just a few steps.

The key component here is the SiYuan publishing script, which allows you to pragmatically get your blog files and format them in a way that is compatible with Astro.

Step 1: Write your blog posts!

A blog is as good as its content, so make sure to take care of it. The publishing script will take care of everything, so feel free to format the document as you like. You can even include embedded assets, like images. Just remember that, at the end of the day, the script produces Markdown files, so you should not expect non-standard Markdown features to work (like the horizontal layout for superblocks).

Note that the name, icon, tags, and other parameters you give to your document are exclusively for your own reference, and they will have no impact on the blog posts. You will need to specify those things in the frontmatter.

Step 2: Write the frontmatter

A crucial part of posts in Astro blogs is the frontmatter, which includes some metadata such as the publishing time, tags, etc.
In order to simplify the work of the script (and that of the blog writer, since SiYuan's UI for managing the frontmatter is not particularly smooth), I have decided to make the script expect the frontmatter to be inside the document itself, inside a YAML code block.

The script will automatically remove all lines before the frontmatter, so make sure you include the frontmatter at the top of the document.

After writing the frontmatter, your post should look something like this:

When editing the post content, you can ALT-click on the code block icon (or right-click > Fold/Expand) to fold the frontmatter. Do the same when you need to edit the frontmatter again to expand it.

Step 2.5: Setting the article cover

Articles look the best when they have a good cover image. Let me teach you how to add one.

First, add the intended cover image inside your document, before the frontmatter. Right-click on the image, then copy the image URL.

You can then add this URL to your frontmatter code block, by adding a line like:

ogImage: assets/cover-2-20250419183127-m80hhsq.webp

with the path you just copied instead of the example one. Your document should now look like this:

Since the image is before the frontmatter, it will not be included in the rendered blog post. Normally, the blog post layout already includes the ogImage, so if you place it under the frontmatter, it will likely be rendered twice.

If you're annoyed by the image taking up precious space in your document, you can delete it. But then, if it's not used anywhere else, SiYuan will mark it as an unused asset, and it will suggest you to delete it from the workspace, which will cause issues.
For this reason, I like to set it as the document cover in SiYuan, so that it doesn't get flagged as an unused asset.

Your final result should look like this:

Step 3: Prepare your Astro website

Now is time to include the SiYuan Publishing script in your website. You only need to do this once.

You can simply copy the script from Git, and paste it in your website as siyuan.mjs. Then you can edit the package.json file to include, under "scripts", "siyuan": "node path/to/siyuan.mjs",.

On my website, I placed the publishing script in src/utils/siyuan.mjs, and now my package.json looks like this:

{
  // ...
  "scripts": {
    "dev": "astro dev --host",
	// other scripts like build, start, ...
    "siyuan": "node src/utils/siyuan.mjs",
  },
  // ...
}

Full file here

Now, before you run the script, you must set the environment variable BLOG_NOTEBOOK_ID to the ID of the notebook containing your blog posts.

To get it, right-click on the notebook with your posts in the doc tree, then Settings, then Copy ID.

You can now create an .env file with ``BLOG_NOTEBOOK_ID=id_you_just_copied` in your project root, or have the variable set however you like.

Step 4: Enjoy

Run npm run siyuan and enjoy.

The script will automatically download your posts, format them, and set put them in the src/content/blog folder. If your website expects the blog files to be in another location, just change Line 10 of the script to the correct one.

Questions? Issues? Leave them in the comments below. Happy blogging!