Advanced HTML Export

by fnumatic
5
4
3
2
1
Score: 51/100

Description

Export Obsidian notes as self-contained HTML

Reviews

No reviews yet.

Stats

1
stars
529
downloads
1
forks
7
days
6
days
6
days
12
total PRs
0
open PRs
1
closed PRs
11
merged PRs
0
total issues
0
open issues
0
closed issues
192
commits

Latest Version

6 days ago

Changelog

0.15.0 (2026-11-13)

Features

  • settings: drive autosave through the export folder (e4cb59d)

README file from

Github

Obsidian Advanced HTML Export

Export Obsidian notes as self-contained HTML files with advanced features for sharing and archiving.

Pitch

Turn your entire wiki into a single HTML file. Export one note or your whole network of linked notes — either way, you get one portable, self-contained file that's easy to share, archive, or send to anyone. No broken links, no missing assets, no hassle.

What is this plugin for

The Advanced HTML Export plugin allows you to export individual Obsidian notes as self-contained HTML files. Key features include:

  • Self-contained exports: All CSS is embedded, no external dependencies
  • Clean formatting: Uses GitHub-style markdown rendering with responsive design
  • Safe filenames: Automatically generates web-safe filenames
  • Progress feedback: Shows export progress and completion notifications
  • Current file export: Quick export of the currently active note via command palette
  • Bulk wiki export: Export entire wikis as single HTML with SPA navigation
  • Wiki link resolution: Automatically resolves [[Wiki Links]] across all notes
  • Sidebar navigation: Collapsible sidebar with page list and search

Why another HTML export plugin

While Obsidian has built-in HTML export capabilities, this plugin offers several advantages:

  • Clean export of inline nested notes: Properly handles and displays nested note structures with clean formatting
  • TOC with fully working links: Generates table of contents with functional internal links for navigation within complex documents
  • Export renderings of other plugins: Captures and exports the rendered output from other Obsidian plugins (like Dataview, Kanban, etc.)
  • Smallest HTML files possible: Produces highly optimized, minimal HTML files even when embedding images and other assets

Wiki Export

Export a network of linked notes as a single HTML file with single-page application navigation.

Features

  • Single HTML file: All notes embedded in one portable file
  • SPA navigation: Instant page switches without reload
  • History support: Browser back/forward buttons work
  • Breadcrumb navigation: Shows current location in wiki
  • Collapsible sidebar: Hide/show navigation panel
  • Page search: Filter pages in sidebar

Usage

  1. Open any note in the wiki
  2. Run "Export wiki as HTML" from command palette
  3. All linked notes are collected and exported
  4. Open the HTML file - navigate between pages using the sidebar or links

Embedding Excalidraw into your Notes and Exporting

Prerequisites

Ensure you have the Obsidian Excalidraw Plugin installed and enabled.

Configuration

To include Excalidraw diagrams in your exported HTML, configure the following settings in the Excalidraw plugin:

  1. Open Excalidraw Settings

    • Go to Settings → Community Plugins → Excalidraw
  2. Enable SVG Export

    • Find the "Export" section
    • Enable "Export as native SVG"
    • This ensures diagrams are embedded as actual SVG markup rather than temporary blob URLs

Usage

Once configured, embed Excalidraw diagrams in your notes using wiki-links:

![[my-diagram.excalidraw]]

The diagrams will be automatically converted to embedded SVG when exporting to HTML.

Troubleshooting

Problem: Excalidraw diagrams appear as empty placeholders or don't render
Solution: Verify "Export as native SVG" is enabled in Excalidraw settings

Installation

  1. Install the BRAT plugin from Obsidian's community plugins
  2. Open BRAT settings and add this repository: fnumatic/obsidian-advanced-html-export
  3. Enable the plugin in your Obsidian settings

Manual Installation

  1. Download the latest release from the GitHub releases page
  2. Extract the files to your vault's .obsidian/plugins/obsidian-advanced-html-export/ directory
  3. Reload Obsidian and enable the plugin in settings

Usage

Single File Export

  1. Open any note in Obsidian
  2. Use the command palette (Ctrl/Cmd + P) and search for "Export Current File as HTML"
  3. The file will be exported as a self-contained HTML file and downloaded to your default downloads folder
  4. Open the HTML file in any web browser to view the formatted note

Wiki Export

  1. Open any note in your wiki (a note with [[Wiki Links]] to other notes)
  2. Use the command palette (Ctrl/Cmd + P) and search for "Export wiki as HTML"
  3. All linked notes are collected and exported to a single HTML file
  4. Open the HTML file to navigate between pages using the sidebar or links

Timestamped filenames

Timestamps are off by default, so a fresh installation writes My Note.html. Add a format under Settings → Advanced HTML Export → Export options → Timestamp format to enable them. The settings page shows a live preview of the resulting filename.

Example with YYYY:

  • My Note-2026.html
  • 01-central-note-wiki-2026.html

Automatic saving

By default an export is downloaded by the browser, which may ask where to put the file. Set Settings → Advanced HTML Export → Automatic saving → Export folder (for example exports) to write exports straight into that vault folder instead, so no file dialog appears. The folder is created on the first export. Clear the field to download again.

Overwrite existing exports decides what happens when the name is taken: on, the file is replaced; off, the export becomes My Note-1.html, My Note-2.html and so on. Combined with a timestamp format you get one file per run, or one file per period when the format is coarser (for example YYYY-MM-DD).

Supported tokens:

Token Meaning Example
YYYY four-digit year 2026
YY two-digit year 26
MM month 10
DD day 26
HH hours (24h) 16
mm minutes 30
ss seconds 05

Other characters are kept as literals. Spaces and characters that are invalid in filenames become underscores. An empty format disables timestamps and is the default.

Override the format per note in the frontmatter:

---
export:
  timestamp: "YYYY-MM-DD"
---

Disable the timestamp for one export:

---
export:
  timestamp: false
---

Use the global format, falling back to the default when the setting is empty:

---
export:
  timestamp: true
---

For a wiki export, the value comes from the start note. For a single-file export, it comes from the exported note. The frontmatter value wins over the setting.

Exclude notes from an export

The start note of a wiki export can exclude notes through its frontmatter:

---
export:
  exclude:
    tags: [companion]
    folders: [Kurse/Begleitmaterial]
    links: ["Companion Note", "Glossar"]
---
  • tags matches frontmatter and inline tags; the leading # is optional.
  • folders matches the folder and its subfolders.
  • links accepts note names or vault paths.
  • Excluded notes are skipped and their outgoing links are not followed.
  • The start note itself is always included unless it has publish: false.
  • publish: false is a global hard exclusion and is not overridden.

The rules apply only to the export started at that note. To export the excluded notes, start another export at a note that links them and has no export.exclude rules — for example a companion-notes hub that the course note links to. Add that hub to links as well if it should not appear in the course export.

Export Compression

Exports can optionally be wrapped in a self-extracting, compressed HTML container. The resulting file stays a single .html file and unpacks itself in the browser using the native DecompressionStream — no server or external assets required.

Configure it under Settings → Advanced HTML Export → Export options → Export compression:

Option Description
None Plain HTML (default)
gzip + base64 gzip-compressed payload, base64-encoded
gzip + base85 gzip-compressed payload, base85-encoded (~6% smaller than base64)

Override per note

The start note of an export can override the global setting via its frontmatter:

---
export:
  compression: gzipb85
---

Accepted values are none, gzipb64 and gzipb85. The resolution order is: frontmatter → plugin setting → none. An absent or invalid value falls back to the plugin setting, and none can be used to disable compression for a single note.

Opening a compressed export briefly shows an "Unpacking…" screen. It requires a browser with DecompressionStream support (Chrome 80+, Firefox 113+, Safari 16.4+).

Export Statistics

It is often unclear what actually fills up an exported file. Enable Settings → Advanced HTML Export → Export options → Show export statistics to open a size overview after each wiki or single-file export (default: off).

The overview is measured exactly while rendering and shows:

  • Headline sizes — the output file size, the uncompressed HTML size and, when compression is enabled, the gzip payload plus the encoding overhead (base64/base85).
  • By category — note markup, images, diagrams, code blocks, CSS and JavaScript, each with bytes, share and a proportional bar. The categories are mutually exclusive and sum to the uncompressed HTML size.
  • Images by format — embedded bytes per format (webp, png, jpeg, svg, gif, …).
  • Largest artifacts — the five biggest individual contributors (notes, images, diagrams, code blocks) ranked by size, shown as a table with kind, original name, export type and size. The original name is the source file where one exists (image files, embedded .excalidraw diagrams) and otherwise the source note; the export type is what the artifact becomes in the file (image format such as webp, svg for Excalidraw drawings or the diagram type for other engines, code language, HTML for notes).
  • Vault vs. export — original note and image source bytes compared to the embedded/optimized bytes, including how much identical-image deduplication saved.

Diagram and code block bytes are measured from the rendered elements. Diagram detection is conservative: markup from renderers that are not recognized is counted as note markup instead of being attributed incorrectly.

Development Process

Prerequisites

  • Node.js 22 (LTS)
  • A package manager (pnpm, npm, or yarn)

Setup

  1. Clone the repository
  2. Install dependencies: pnpm install

Development

  • Start development server: pnpm dev

    This launches an interactive development environment that:

    • Scans for Obsidian vaults that have been opened at least once
    • Presents a menu to select which vault to develop against
    • Builds the plugin in watch mode with source maps
    • Automatically copies updated plugin files to the selected vault on each change
Plugin Hot Reload in Obsidian

For automatic plugin reloading in Obsidian without restarting the app, install the Hot Reload plugin from the Obsidian community plugins. This allows your changes to be reflected immediately in the running Obsidian instance.

Building

  • Build for production: pnpm build
  • Preview the built plugin: pnpm preview

Testing

  • Run all tests: pnpm test
  • Run tests in watch mode: pnpm test:watch
  • Type check: pnpm type-check

Plugin UI

The four export dialogs use TypeScript and native DOM views, without a UI framework runtime. Shared components handle buttons, icons and progress bars; the modal base class owns view cleanup. See Native UI for the structure, lifecycle rules and reproducible bundle/browser measurements.

To test the plugin against the real Obsidian without a window or manual clicks, see Headless end-to-end testing.

Release procedure

Releases are managed by release-please. Commits to main are analyzed by the Release Please workflow, which opens or updates a release pull request containing the version bump and the CHANGELOG.md changes.

To release:

  1. Merge the chore(release): release X.Y.Z pull request.
  2. release-please creates the git tag and the GitHub release.
  3. The release.yml workflow builds the plugin and attaches the assets.

Versions follow Conventional Commits (fix → patch, feat → minor; pre-1.0 features bump the minor version). release-please updates the version in manifest.json; versions.json is synced automatically once the release has been created.

Artifacts generated

  • Built plugin files (main.js, manifest.json, styles.css)
  • CHANGELOG.md with release notes
  • GitHub release with the three plugin files and build provenance attestations
  • Version tags in git

GitHub Actions

  • release-please.yml: Creates/updates the release PR and, on release, the tag and GitHub release
  • release.yml: Triggers on version tags, builds the plugin and attaches the release assets

Standing on shoulders of giants