README file from
GithubObsidian 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
- Open any note in the wiki
- Run "Export wiki as HTML" from command palette
- All linked notes are collected and exported
- 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:
-
Open Excalidraw Settings
- Go to
Settings → Community Plugins → Excalidraw
- Go to
-
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
Via BRAT Plugin (Recommended)
- Install the BRAT plugin from Obsidian's community plugins
- Open BRAT settings and add this repository:
fnumatic/obsidian-advanced-html-export - Enable the plugin in your Obsidian settings
Manual Installation
- Download the latest release from the GitHub releases page
- Extract the files to your vault's
.obsidian/plugins/obsidian-advanced-html-export/directory - Reload Obsidian and enable the plugin in settings
Usage
Single File Export
- Open any note in Obsidian
- Use the command palette (
Ctrl/Cmd + P) and search for "Export Current File as HTML" - The file will be exported as a self-contained HTML file and downloaded to your default downloads folder
- Open the HTML file in any web browser to view the formatted note
Wiki Export
- Open any note in your wiki (a note with [[Wiki Links]] to other notes)
- Use the command palette (
Ctrl/Cmd + P) and search for "Export wiki as HTML" - All linked notes are collected and exported to a single HTML file
- 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.html01-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"]
---
tagsmatches frontmatter and inline tags; the leading#is optional.foldersmatches the folder and its subfolders.linksaccepts 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: falseis 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
.excalidrawdiagrams) and otherwise the source note; the export type is what the artifact becomes in the file (image format such aswebp,svgfor Excalidraw drawings or the diagram type for other engines, code language,HTMLfor 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
- Clone the repository
- Install dependencies:
pnpm install
Development
-
Start development server:
pnpm devThis 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:
- Merge the
chore(release): release X.Y.Zpull request. - release-please creates the git tag and the GitHub release.
- The
release.ymlworkflow 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 releaserelease.yml: Triggers on version tags, builds the plugin and attaches the release assets