Obsidian Homebrewery

A Homebrewery-compatible authoring and preview environment for Obsidian.

The goal of this plugin is to make Homebrewery documents first-class citizens inside an Obsidian vault while preserving compatibility with the original Homebrewery format.

Write normal Homebrewery Markdown, keep the source portable, and get a live rendered preview directly beside the Obsidian editor.

This project is under active development and is not yet published as an Obsidian Community Plugin.

---

Why this project?

The Homebrewery is an excellent tool for creating tabletop RPG documents, but its editing workflow lives outside a traditional knowledge base.

This plugin explores a different workflow:

• keep Homebrewery documents as normal Markdown files
• edit them directly inside Obsidian
• preserve compatibility with upstream Homebrewery
• render them with high visual fidelity
• keep assets and themes manageable locally when desired
• progressively add Homebrewery-aware editing tools without introducing a custom document format

A core design rule of the project is:

The source belongs to Homebrewery, not to the plugin.

The plugin should adapt around valid Homebrewery documents rather than requiring documents to adapt around the plugin.

---

Current Features

Homebrewery V3 rendering

• Uses the actual Homebrewery V3 rendering pipeline rather than reimplementing Homebrewery syntax with a generic Markdown renderer.
• Supports upstream V3 page structure and rendering behavior.
• Bundles the required upstream theme resources.
• Supports Homebrewery custom CSS and imported community styles.
• Preserves the original source document during rendering.

High-fidelity preview

The preview is rendered inside an isolated persistent iframe.

Current preview features include:

• split Obsidian editor + Homebrewery preview workflow
• near-live updates from the unsaved editor buffer
• persistent preview DOM between renders
• zoom controls
• optional Homebrewery-style page synchronization
• configurable preview lifecycle:
  • Follow active brew
  • Preview per brew
• source-bound previews with live updates

Validated documents have reached pixel-level visual parity with upstream Homebrewery rendering, including custom community themes and fonts.

---

Homebrewery-aware Obsidian editor

The plugin extends Obsidian's existing CodeMirror 6 editor rather than replacing it.

Current editor features include:

• \page / \pagebreak decorations and page numbering
• \column / \columnbreak decorations
• Homebrewery {{ ... }} block highlighting
• Homebrewery { ... } injection highlighting
• Homebrewery-only activation — normal Markdown files remain unaffected
• native CodeMirror folding for large Homebrewery sections:
  • metadata
  • css

The source remains normal editable Markdown at all times.

---

Editing helpers

A small Homebrewery-aware editing helper layer is also being developed.

Current helpers include:

• New Page
• Column Break
• Homebrewery Block
• Bold
• Italic

New Page is context-aware. Instead of blindly inserting \page, it can inherit the most recent page setup from the current brew.

For example:

{{pageNumber,auto}}
{{footnote,font-size:14.5px Chapter 1 : The Classes}}
\page

This allows a new page to continue the existing page number and footer configuration without introducing plugin-specific syntax.

Low-level editing commands are kept separate from the UI so they can later be reused by hotkeys, the command palette, autocomplete, and a larger snippet system.

---

Asset localization

Homebrewery documents frequently depend on remote images, stylesheets, fonts, and other resources.

The plugin includes an asset discovery and localization pipeline capable of scanning:

• Markdown images
• raw HTML
• srcset
• CSS url(...)
• CSS @import
• fonts
• recursively imported stylesheets

Three asset modes are supported:

• Remote — use upstream URLs normally
• Prefer Local — use localized assets when available
• Local Only — render without requiring remote asset access

Localization happens without rewriting the original Homebrewery source.

---

Settings

The plugin already has a typed settings foundation using Obsidian's native settings system.

Current settings include:

Editor

• Auto-fold metadata on open
• Auto-fold CSS on open

Preview

• Follow active brew
• Preview per brew

The settings architecture is intentionally structured so additional Preview, Assets, Themes, and Advanced options can be added without scattering configuration logic throughout the plugin.

---

Architecture

The project is intentionally split into separate responsibilities:

Homebrewery source
        │
        ▼
      Parser
        │
        ├── metadata
        ├── custom CSS
        └── brew Markdown
        │
        ▼
 Renderer Adapter
        │
        ▼
 Homebrewery V3 engine
        │
        ▼
 Theme / Font / Asset resolution
        │
        ▼
 Persistent sandboxed preview

Editor functionality is kept separate from rendering:

Obsidian CodeMirror 6
        │
        ├── syntax decorations
        ├── page / column structure
        ├── folding
        └── editing commands

This separation is important because future renderer versions should not require rewriting the editor integration.

---

Compatibility philosophy

Upstream Homebrewery is treated as the source of truth.

The project aims to avoid:

• plugin-specific document syntax
• rewriting valid Homebrewery source
• modifying user CSS to make it work inside Obsidian
• approximating Homebrewery rendering with another Markdown implementation

When compatibility requires adaptation, transformations should happen in memory during preview generation whenever possible.

---

Development

Requirements

• Node.js
• npm
• Obsidian for plugin testing

Install dependencies:

npm install

Run the test suite:

npm test

Type-check:

npm run typecheck

Build:

npm run build

The repository also contains a local development deployment workflow for testing the plugin inside an Obsidian vault.

---

Testing

The project uses several layers of testing:

• parser and renderer unit tests
• editor / CodeMirror tests
• preview lifecycle tests
• security regression tests
• asset localization tests
• browser rendering tests
• visual comparison against upstream Homebrewery

Visual compatibility testing is particularly important because apparently-correct HTML is not sufficient when font loading, CSS imports, page geometry, or browser isolation differ from upstream.

---

Roadmap

Editor experience

• Homebrewery page / column decorations
• Homebrewery block / injection highlighting
• Metadata / CSS folding
• Basic editing helpers
• Categorized Homebrewery snippet system
• Additional Homebrewery syntax highlighting
• Autocomplete
• Diagnostics

Preview

• Persistent split preview
• Near-live unsaved updates
• Zoom controls
• Optional upstream-style page synchronization
• Configurable active-brew preview behavior
• Fit Page / Fit Width
• Additional preview controls

Assets

• Dependency scanning
• Asset localization
• Remote / Prefer Local / Local Only modes
• User-facing "Make Local" workflow
• Brew import with localized assets

Themes

• Upstream V3 theme integration
• Community CSS/font compatibility
• Installed theme library
• Community theme import
• Custom theme authoring workflow

Export & compatibility

• PDF export
• Legacy Homebrewery renderer
• Future renderer adapters

---

Project status

The project is usable for V3 Homebrewery editing and previewing, but it is still in active development.

The current focus is building a polished Obsidian-native authoring experience around a renderer that already closely matches upstream Homebrewery behavior.

Breaking changes are still possible before the first stable release.

---

Upstream

This project builds upon and targets compatibility with:

The Homebrewery

https://homebrewery.naturalcrit.com/

Homebrewery remains the authoritative reference for rendering behavior and document syntax.

This project is not affiliated with or endorsed by NaturalCrit.

Third-party Homebrewery resources retain their respective licenses. See the repository's license and third-party notices for details.