Obsidian Blog Engine

A lightweight blog engine that turns your Obsidian vault into a website — no export, no copy-paste. Write in Obsidian, push to GitHub, see it live.

What it does

Your vault folder structure becomes your site's URL structure. A note at blog/My Post.md is served at /blog/My-Post. A note tagged homepage becomes the landing page for its section. That's the whole model.

Features

• Markdown-native — callouts, checkboxes, wiki-links ([Note](/note) and [alias](/note)), image embeds, sliders, <mark>highlights</mark>, footnotes ([^1]) — all rendered from standard Obsidian syntax
• Mermaid diagrams — fenced ```mermaid ``` blocks rendered client-side; dark theme included

• Math / LaTeX — $inline$ and $$block$$ via KaTeX; safe from markdown parser mangling

• Anchor links — [Note › Heading](/note#heading) links to a specific heading within a note

• Audio embeds — ![file.mp3](/filemp3) → <audio> element
• Aliases — aliases: frontmatter for alternate wiki-link names
• Related posts — automatic "See also" section scored by shared tags and section
• Dark / light mode — toggle in the header, remembered across visits
• Inline body tags — #hashtag in post body auto-collected as tags
• Dataview inline queries — `= this.field` evaluated against note frontmatter
• Block references — ^block-id on a paragraph; [Note › id](/note#id) links scroll to it
• Syntax highlighting — fenced code blocks with language labels and a copy button
• Dataview queries — TABLE and LIST queries rendered server-side; supports FROM, WHERE, SORT, LIMIT, GROUP BY with per-group headings
• Lightbox gallery — single image embeds become a full-screen lightbox; multiple on one line become a slider
• Banner images — set banner: in frontmatter for a hero image with configurable focal point
• Private notes — notes without website: true are queryable by Dataview but show a placeholder page instead of their content
• Hot-reload — the server detects file changes and reloads without a restart
• Search — full-text search across all published posts at /search, with tag filter
• Tag pages — every tag gets a /tag/<name> archive page; tags on posts are clickable badges
• Breadcrumb navigation — posts show a Home › Section › Post trail
• Reading time — estimated reading time on post pages and listing cards
• Pagination — listing pages paginate at 20 posts per page
• RSS feed — latest 20 posts at /feed.xml
• Sitemap — auto-generated at /sitemap.xml
• OpenGraph / Twitter Card — per-page meta tags for rich link previews
• JSON-LD structured data — Article, Book, and WebSite schemas for rich Google results
• Next / previous post navigation — "← Older" / "Newer →" links at the bottom of each post, ordered by date within the same section
• Collapsible callouts — > [!type]- Title collapses by default; > [!type]+ is pinned open — uses native <details>
• Visible image captions — ![Caption text](/photojpg) renders a <figcaption> below the image
• Section RSS feeds — every section has its own feed: /blog/feed.xml, /gallery/feed.xml, etc.
• Tags index page — /tags lists every tag with post counts; opt-in by adding show_tags: true to the root homepage
• Vault-wide attachments — if a media file isn't found in the post's own _attachments/, the engine checks _attachments/ at the vault root, then ATTACHMENTS_PATH from .env
• Dataview LIMIT clause — LIMIT N in a dataview block now trims results after sorting
• Author field — author: frontmatter (string or list) shown below the post title and in JSON-LD
• Date last modified — updated: frontmatter shows "Updated …" in post meta and populates dateModified in JSON-LD
• Mobile nav — collapsible hamburger menu on narrow screens; desktop layout unchanged
• Print stylesheet — clean @media print styles for printing or saving as PDF
• Docker-ready — pass a VAULT_REPO build arg to clone your vault at deploy time

How publishing works

1. Write notes in Obsidian as usual
2. Add website: true to a note's frontmatter to publish it
3. Push your vault to its GitHub repo
4. The site rebuilds automatically

No build step, no static site generator, no CMS. Just markdown files and a Python server.

Explore the demo

• Blog — blog posts with callouts, code, images, and checkboxes
• Gallery — an image gallery with lightbox and slider
• Books — a Dataview-powered bookshelf pulled from individual book notes
• The Accidental Existentialist — a root-level standalone page pinned to the nav via menu_order

Standalone pages

Notes placed directly in the vault root (not in any subfolder) get a URL with no section prefix — /slug. They don't appear in any listing, making them ideal for standalone pages like About, Contact, or Uses. Link to them via wiki-links from your content, or pin them to the top nav with menu_order in frontmatter:

---
website: true
title: About
menu_order: 1   # lower = further left in the nav
---