Overview

kazari process takes a folder of built HTML and upgrades every plain code block into a framed, syntax-highlighted Kazari block. The site deploys exactly as before; only the code blocks change.

Install

Requires Go 1.25 or later.

go install github.com/frostybee/kazari/cmd/kazari@latest

Or run it without installing:

go run github.com/frostybee/kazari/cmd/kazari@latest process ./public

Usage

1
kazari upgrades code blocks in built HTML to framed, syntax
2
highlighted blocks with copy buttons, line numbers, and dual themes.
3
4
Usage:
5
  kazari process [dir] [flags]   upgrade code blocks under dir (default ".")
6
  kazari themes                  list bundled syntax theme names
7
  kazari version                 print the kazari version
8
  kazari help                    show this help

Why post-build

Kazari integrates into a site through two paths, each with different requirements.

The library path renders blocks while the page is built. A Go program calls engine.RenderWithMeta() directly, or wires the Goldmark extension into its Markdown pipeline. Kazari sees the fence info string exactly as the author typed it, so every meta string feature works with no extra setup. This path needs a Go Markdown pipeline that is yours to change.

The post-build path exists for sites where the Markdown pipeline is not yours to change. It takes the finished HTML, recovers the source text from whatever markup the generator produced, and re-renders each block through the same engine. Nothing about the generator has to change.

The tradeoff is the fence info string. Generators discard it before HTML exists, so features driven by per-block meta cannot survive on their own. A one-file render hook writes that text into the HTML and closes the gap where the generator supports one.

Both paths run the same engine and read the same kazari.config.yaml format, and recovered source renders byte-identical to the same source going through Goldmark. Moving between them changes the wiring, not the output.

How it works

The processor walks every .html and .htm file under the target directory, finds each code block, recovers the original source text from the markup, and re-renders it through the Kazari engine. Everything outside the replaced blocks passes through untouched. Running the command a second time produces zero changes, which makes it safe as an unconditional build step.

kazari.css and kazari.js are written once at the output root and linked from every page that gained a Kazari block. See Configuration for asset options.

What works with zero setup

These features need no configuration and no changes to the source site, because their triggers survive the build: engine config, the code text itself, or generator markup that gets translated.

• Editor and terminal frames with automatic detection
• Copy, fullscreen, and wrap buttons
• Theme toggle and dual light and dark themes
• Language badge and file icons
• Line numbers and word wrap via config defaults
• Threshold-based collapsible sections
• Terminal comment stripping, links, and localization
• Filename comment extraction (a // main.go first line becomes the title)
• Output panel via the ---output--- separator line
• Hugo and Chroma hl_lines classes translated to marked lines
• Plain diff rendering for language-diff blocks
• Mermaid blocks detected and left untouched

What needs a render hook

Features driven by the fence meta string cannot survive a normal build: generators discard that text before HTML exists. A one-file render hook preserves them.

• Explicit titles (title="main.go")
• Line markers with explicit ranges, including labeled ranges
• Focus lines (focus="4-6")
• Explicit collapse ranges and collapse styles
• Hybrid diff (diff lang="go")
• Per-block theme overrides, including a light and dark pair
• startLineNumber and per-block showLineNumbers, wrap, preserveIndent, or hangingIndent overrides
• Output panel controls: withOutput, outputLabel, outputCollapsed

Feature availability by generator

Dry-run mode

--check computes every change without writing anything. It prints the path of each file and asset that would change, one per line, then a summary:

1
public/docs/index.html
2
public/kazari.css
3
public/kazari.js
4
14 files, 22 blocks upgraded, 1 skipped, 0 suppressed, 3 changed

The same summary line prints on every run: files scanned, blocks upgraded, blocks skipped, blocks suppressed inside existing Kazari markup, and files changed.

Try it

Browse the live example site to see every feature rendered, or follow the Hugo Integration guide to build and process it locally.