obsidian-to-blog

Generate static HTML sites from Obsidian vaults using the official Obsidian CLI.

Given an entrypoint markdown file, obsidian-to-blog traverses the link graph and generates HTML pages for all connected notes — including links generated by plugins like Dataview.

Features

Full plugin support: Extracts rendered HTML after plugins (Dataview, etc.) have processed
Link graph traversal: Automatically discovers and exports all linked pages
Image handling: Copies referenced images to the output directory (respects vault's attachments folder config)
Frontmatter extraction: Stores YAML frontmatter as JSON in a <script> tag
Clean output: Generates minimal, unstyled HTML pages with Obsidian UI elements removed

Requirements

Node.js 18+
Obsidian 1.12.4+ (with CLI enabled)
Obsidian must be running when you execute the command

Enabling the Obsidian CLI

Open Obsidian
Go to Settings → General
Scroll to Command line interface
Click Register CLI and toggle it on

For more details, see the Obsidian CLI documentation.

Installation

# Clone and build
git clone https://github.com/geooot/obsidian-to-blog.git
cd obsidian-to-blog
pnpm install
pnpm build

# Or install globally (after building)
pnpm link --global

Usage

# Basic usage (from your vault directory)
obsidian-to-blog -e "Home.md"

# Specify output directory
obsidian-to-blog -e "Blog/Index.md" -o ./public

# Specify vault path
obsidian-to-blog -e "Home.md" -v ~/Documents/MyVault

# With all options
obsidian-to-blog \
  --entrypoint "Blog/Index.md" \
  --output ./public \
  --vault ~/Documents/MyVault \
  --wait-for-plugins 1000 \
  --verbose

Options

Option	Short	Description	Default
`--entrypoint`	`-e`	Starting markdown file (required)	-
`--output`	`-o`	Output directory	`./dist`
`--vault`	`-v`	Path to Obsidian vault	Current directory
`--wait-for-plugins`	`-w`	MS to wait for plugin rendering	`500`
`--verbose`		Enable verbose logging	`false`

How It Works

Connect to Obsidian: Uses the Obsidian CLI to communicate with a running Obsidian instance
Crawl the link graph: Starting from your entrypoint, discovers all linked files using:
- Parsed [[wikilinks]] and [markdown](links) from raw content
- <a href> links extracted from rendered HTML (catches plugin-generated links)
Extract rendered HTML: For each file:
- Opens the file with obsidian open
- Switches to preview mode if needed (checks current mode first)
- Waits for plugins to render
- Extracts the DOM HTML with obsidian dev:dom
Generate output: Creates standalone HTML pages with:
- Rewritten internal links (.html extensions, same-tab navigation)
- Copied image assets (from vault's configured attachments folder)
- Frontmatter stored as <script type="application/json" id="frontmatter">
- Removed Obsidian UI elements (collapse indicators, backlinks panel, metadata display)

Output Structure

dist/
├── home.html              # Your entrypoint
├── linked-note.html
├── folder/
│   └── nested-note.html
└── assets/
    ├── image1.png
    └── image2.jpg

Frontmatter

If your notes have YAML frontmatter, it's extracted and embedded as JSON:

<head>
  <script type="application/json" id="frontmatter">
    { "title": "My Post", "tags": ["blog", "tech"], "published": true }
  </script>
</head>

Plugin Support

Since obsidian-to-blog extracts rendered HTML after plugins have run, it supports plugins that:

Render content (Dataview, Tasks, etc.)
Generate internal links (Dataview tables linking to notes)
Insert images or media

The extracted HTML includes whatever Obsidian displays in preview mode.

Styling

The generated HTML is intentionally unstyled — just the content with Obsidian's CSS class names. You can:

Add a <link> to your own stylesheet
Use Obsidian's CSS classes as hooks for styling (e.g., .el-p, .el-h1, .dataview)
Post-process the HTML with your own tools

Troubleshooting

"Could not connect to Obsidian"

Make sure Obsidian is running
Verify CLI is enabled in Settings → General → Command line interface
Try running obsidian version in your terminal

"File not found"

Check the file path is relative to your vault root
Include the .md extension or omit it — both work

Plugin content not rendering

Increase --wait-for-plugins (try 1000-2000ms)
Make sure the plugin is enabled in your vault

Images not found

Check images exist in your vault's attachments folder
The tool reads your vault's attachmentFolderPath config
External URL images are kept as-is (not downloaded)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

# Lint
pnpm lint

# Format
pnpm format

# Run all checks
pnpm check

License

MIT

To Blog