Turn Obsidian notes into a website

Q: Can I publish only part of my vault?

Yes. Only what you put into content/ becomes a page. Keep a separate folder for public notes.

What carries over

In Obsidian	On a HERON site
A note `Recipes/Bread.md`	A page at `/recipes/bread/`
A folder of notes	A section with a list of its pages
Headings, lists, tables, bold, code	The same, unchanged
Properties at the top of a note	The settings block of a page: `title`, `h1`, `description`
`[[Bread]]` links between notes	Standard Markdown links: `[Bread](address)`
`![[photo.jpg]]` embeds	Images `![Bread loaf](/media/bread.jpg)` in `media/`
Callouts `> [!note]`	A quote block `>`
Tags, graph, canvas	Not published

What to change in the notes

Links

HERON reads standard Markdown links. Wiki-style double-bracket links need converting once, and after that you write links the standard way.

For new notes: In Obsidian, Settings → Files and links → turn off "Use [[Wikilinks]]". New links are then written in the standard form.
For old notes: Convert them once with a find-and-replace or a community plugin, or ask an AI agent to do it across the folder.
What a standard link looks like: [First site](/docs/first-site/): the text in square brackets, the address in round ones.
Links between your pages: Write the address from the root without the language prefix, like /recipes/bread/. HERON turns it into the right address for each language.
Check: The build lists every link that leads nowhere, with the file and line, so nothing broken slips through.

Page settings

Every page starts with a short settings block, the same place Obsidian keeps properties. Three fields matter most; the rest have hints next to them.

title: The line shown in search results, up to 60 characters. Example: Sourdough bread at home: a simple recipe.
h1: The heading on the page. It can be shorter than title: Sourdough bread.
description: One or two sentences for search results, up to 155 characters: what the reader gets on the page.
Obsidian properties you already have: date can stay: HERON reads it as the publication date. For other properties, run heron check .: the report says which fields it does not accept.
Easiest start: Copy a page HERON created, keep its settings block and paste your note below it.

Sections

Long notes are split into sections with a short label after the heading. The label is what lets the theme draw a list as cards, steps or a table.

Write: ## Ingredients {#ingredients} instead of ## Ingredients.
Why: The label is the address of the section, /recipes/bread/#ingredients, and tells the theme how to lay it out.
Labels: Latin letters, digits and hyphens: {#how-to-bake}. Each label once per page.
Intro: Keep one or two paragraphs before the first section. The strict build points to the file if there are more.
What becomes what: A numbered list turns into steps, a table into a table, questions with ### into an FAQ. See all of them in the forms reference.

Images and private notes

Images go into the media/ folder, private notes stay out of the site folder. Only what you put into content/ can ever be published.

Images: HERON makes WebP and AVIF in every size, so large photos are fine.
How to insert: ![Bread on a board](media/examples/photo.jpg). The text in square brackets is the description for people who cannot see the image; do not leave it empty.
Private notes: Only files inside content/ are published. Keep the vault separate and copy what is public, or set published: false on a page.
Drafts: published: false keeps a page out of the site. noindex: true publishes it but hides it from search and llms.txt.
Attachments: PDF and other files also go to media/; link to them like to a page.

Step by step

1
Create the site

One command takes the latest HERON image, and the image creates the site folder with a theme and demo pages.
2
Copy the notes

Put the public notes into the folder of your language inside content/, keeping the folders.
3
Fix links and settings

As described above. The build lists every broken link with its file and line.
4
Preview

Open localhost:8000 and click through.
5
Publish

When everything is ready, publish the finished site the way you chose. For notes the free way fits well: GitHub Pages with your own domain.
Store and publish
6

Publish on GitHub Pages with your domain
7

Pages and sections in detail
8

How sections become blocks: the forms reference

Why not keep editing in Obsidian?

You can. Open the site folder content/ as an Obsidian vault and write as usual. Git keeps history, and every push publishes the changes. The only rule: use standard links and the settings block on top.

Questions

Is this an alternative to Obsidian Publish?

For public sites, yes. Obsidian Publish is a paid hosted service that keeps the Obsidian look, graph and wiki links. HERON builds a site you own and host anywhere for free, in exchange for a little preparation of links and page settings.

Can I publish only part of my vault?

Yes. Only what you put into content/ becomes a page. Keep a separate folder for public notes.

Do search engines find the pages?

Yes. Every page gets its own address, title, description, a place in the sitemap and llms.txt, and the tags search engines expect.

Can the site be in two languages?

Yes. Notes in a second language go into that language's folder inside content/, with matching file names. See multilingual websites.

From Obsidian notes to a website