Markata Feed

Shared Markdown content starters

2026-11-01T00:00:00Z

Use a Markdown starter to define how a new page begins. The same starter is available to markata-go new, its interactive TUI, and the web workbench.

Create content-templates/guide.md:

---
starter:
  name: guide
  description: A structured guide with an introduction, steps, and summary.
  aliases:
    - tutorial
_directory: guides
templateKey: guide
title: "{{title}}"
date: "{{date}}"
published: false
tags: []
---

## Introduction

## Steps

## Summary

The file name supplies the starter name when name is omitted. _directory sets its default output directory. description and aliases help users find it in the editor. These metadata keys are not copied to the new page.

The shared variables are {{title}}, {{slug}}, {{date}}, and {{datetime}}. They work in frontmatter and body text. Unknown variables stay as written, which lets another renderer use its own syntax.

Run markata-go new --list to see starters, then create content with:

markata-go new "My Guide" --template guide

The web workbench discovers starters from the same configured content_templates.directory (default: content-templates). The CLI and interactive TUI use that same directory. Existing TOML-defined templates and built-ins remain available.

See the CLI reference and starter specification for the full format and precedence rules.

Static SVG visualization foundation

2026-10-31T00:00:00Z

Markata is developing a shared backend rendering pipeline so diagrams and charts can arrive as finished SVG assets, with no visualization engine running in the reader’s browser.

Availability: This is a developer-only foundation in pkg/visualizations. There is no supported d2 or vega-lite Markdown fence, site configuration section, or new markata render capability yet. The existing mermaid and chartjs syntax and output are unchanged.

What the foundation provides #

A backend renderer produces SVG bytes from a request. The common package then checks bounded SVG output, derives intrinsic dimensions, assigns a SHA-256-based filename, publishes the asset and emits normal HTML for a figure:

source + palette + font + renderer/version + options
       |
       v
backend Renderer.RenderSVG(ctx, request)
       |
       v
Pipeline (in-process cache and concurrent coalescing)
       |
       v
NewSVGAsset -> Publish(outputDir, asset)
       |
       v
<figure><img src="/assets/visualizations/<sha256>.svg"
             width="960" height="540" alt="..."></figure>

The filename depends on the exact SVG bytes; renderer cache identity also includes the renderer version, theme content hash, and effective options. Repeated assets can be reused by the browser or a CDN.

Integrate a backend in Go #

An adapter implements this interface (shown here for reference, not as a working D2 integration):

type Renderer interface {
    ID() string
    Version() string
    RenderSVG(context.Context, visualizations.Request) ([]byte, error)
}

Use visualizations.Pipeline.Compile(ctx, backend, request) for a rendered Asset. visualizations.Publish(outputDir, asset) writes a final static asset; visualizations.FigureHTML(asset, alt, caption, aboveFold) returns escaped markup with an explicit image width and height.

The request must include all layout-affecting inputs, especially theme and font contents. Renderers must obey context cancellation and return actionable errors for unsupported syntax, oversized SVG output, or unavailable layout dependencies.

go test ./pkg/visualizations/...
go test -race ./pkg/visualizations/...
go vet ./pkg/visualizations/...

Why the constraints matter #

No layout shift from unknown image dimensions: the figure includes intrinsic width and height. Responsive site CSS still has to preserve the intended image aspect ratio.
No visualization JavaScript on the published page: the output is a normal external SVG image, not a browser chart/canvas library.
Smaller repeat views: a fingerprinted path enables stable cache identities, but Brotli/gzip and appropriate response headers remain hosting responsibilities.
Bounded processing: one SVG has a 4 MiB uncompressed size limit, and the in-process cache holds up to 128 assets or 32 MiB.
Clear trust boundary: the XML checks reject many active/remote constructs but are not a complete SVG sanitizer, and do not guarantee a fully offline page. Author-supplied images and linked resources still need a separate output audit.

The current restrictions also reject some legitimate SVG features such as hyperlinks, embedded images, animation, and foreignObject. Test representative outputs before using a new engine. Large embedded fonts and complex SVG paths can still increase network and browser-paint cost.

What comes next #

D2 is the intended first backend adapter, followed by Vega-Lite through vl-convert, once each meets compatibility and performance checks. Site-builder integration will need base-path-aware asset links and a version-compatible addition to the existing render asset manifest.

Mermaid and Chart.js remain the supported authoring tools until those follow-ups land. See the Markdown guide, accessible Chart.js figures, and renderer interoperability contract.

For exact technical invariants, see spec/spec/STATIC_VISUALIZATIONS.md (after this PR merges).

Warm renderer pool for FastAPI

2026-10-31T00:00:00Z

The Python standalone render API normally starts the bundled Go executable for each call. Applications that render repeatedly can instead own a fixed pool of persistent renderer processes using RendererPool. The pool is started and stopped by the application’s lifespan; no separate daemon or CLI setup is required.

FastAPI lifespan integration #

from contextlib import asynccontextmanager

from fastapi import FastAPI, Request
from pydantic import BaseModel
from markata import RendererPool

class Preview(BaseModel):
    markdown: str

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with RendererPool(workers=2, max_pending=64, workspace='.') as pool:
        app.state.renderer_pool = pool
        yield

app = FastAPI(lifespan=lifespan)

@app.post("/preview")
async def preview(body: Preview, request: Request):
    result = await request.app.state.renderer_pool.render(body.markdown)
    return {"html": result.html, "features": result.features,
            "assets": result.assets}

The pool starts all workers at startup, verifies the persistent protocol via a capability request, and maintains a queue of idle renderers. Each worker is one bundled Go process that handles sequential JSON-lines requests. Requests can run concurrently across workers. The Go protocol caches configured parser instances so subsequent requests avoid parser reinitialization too.

Set inline_assets=True to embed styles and scripts in the returned result or serve result.assets separately, as with markata.render_async. Rendering options unsafe, asset_base, and inline_assets can be supplied on individual pool requests.

Lifecycle and limits #

workers=2 starts two subprocesses per running application process. With uvicorn --workers 4, that is eight Go subprocesses. Size the pool accordingly; it does not share processes across Uvicorn workers.
max_pending=64 limits the number of waiting requests in addition to the currently active worker slots. When saturated, callers receive RenderError rather than growing an unbounded backlog.
render(..., timeout=30) covers queue wait and rendering. A timed-out or cancelled in-flight request kills and replaces that worker so a late result cannot contaminate a later request.
Unexpected child exit or broken protocol also replaces the affected process. A failed replacement makes the pool report an error rather than hang forever.
Exiting the lifespan terminates and reaps its child processes. Do not share the pool across Python event loops or fork a process after starting it.
Requests retain the standalone renderer’s 200,000-byte source limit. The wire protocol has a 1 MiB request frame limit.

The pool requires a bundled Go executable supporting markata render --stdio. The original render() and render_async() remain backward-compatible one-shot APIs and do not implicitly start a pool.

An optional workspace='.' loads Markata’s site configuration once at startup, matching the standalone Python renderer’s workspace behavior. Restart the pool after changing configuration. This is not an HTML sanitizer; keep unsafe=False for untrusted authored HTML and apply your application’s own safety policy.

Performance verification #

Measure median and p95 of warm pool calls versus render_async() on the same machine, with at least 100 requests for each fixture. Also measure throughput at concurrency 1, 2, and 4, resident memory per pool worker, initial startup latency, and large Chart.js response transfer. The existing standalone Go benchmarks are not end-to-end pool timings. Do not assume the same latency until the Python-to-Go pipe and JSON costs are measured.

PyPI installation of Go Markata using Simon Willison’s go-to-wheel

2026-10-31T00:00:00Z

Decision (October 18, 2026): pip install markata should install the Go implementation. This is an intentional handoff of the existing PyPI distribution name, not a rename of the Python import-compatible library. Markata remains on the 0.x release line. Existing Python releases remain immutable on PyPI and in WaylonWalker/markata-py.

Packaging tool #

We use Simon Willison’s go-to-wheel (version 0.2) to compile our ./cmd/markata Go CLI into eight native wheels:

Linux amd64/arm64, both glibc and musl (four wheels).
macOS Intel and Apple Silicon (two wheels).
Windows amd64 and arm64 (two wheels).

go-to-wheel requires the go.mod directory to also be the CLI package. Markata’s CLI is under cmd/markata. Our scripts/build-pypi-wheels.sh temporarily copies its existing main.go into the module root solely for compilation, then removes it, preserving the canonical CLI implementation and normal Go module. It sets version and commit metadata in the built binary.

When installed, markata is a minimal Python entry point which executes the bundled Go binary, not the historical Python Markata CLI or library. There is no network download at first run and no Go compiler required on end-user machines.

Build and test, without publishing #

Run from the Go repository root with Go 1.27 and Python 3.10+:

python -m pip install 'go-to-wheel==0.2'
bash scripts/build-pypi-wheels.sh 0.14.0.dev0
MARKATA_WHEEL_VERSION=0.14.0.dev0 python scripts/check-pypi-wheels.py dist/pypi-wheels

python -m venv .venv-markata
. .venv-markata/bin/activate
python -m pip install ./dist/pypi-wheels/markata-0.14.0.dev0-py3-none-manylinux_2_17_x86_64.whl
markata --help
markata version

The wheel CI workflow automatically repeats the build and verifies tags, embedded OS executables, metadata, installation in a clean venv, and python -m markata.

Publishing the name handoff #

As of this documentation change, the public PyPI project is still Python Markata until a Go wheel upload succeeds and is confirmed on PyPI. The existing Python release markata==0.10.0 remains available as a pin. The newest prior Python prerelease is 0.11.0.dev11. PyPI does not permit replacing those immutable files with Go binaries.

To publish Go Markata (first proposed PyPI Go version: 0.14.0), the owner must do the following once:

Sign into the existing PyPI markata project, open Publishing, and add a GitHub Actions Trusted Publisher:
- owner: WaylonWalker
- repository: markata
- workflow filename: pypi-go-wheels.yml
- environment: pypi
In GitHub WaylonWalker/markata, create or verify a pypi environment with protection (reviewers and restrictions to main) so an unreviewed workflow cannot publish packages.
Once CI passes and the trusted publisher is configured, open Actions → Go Markata PyPI wheels → Run workflow, on branch main, set:
- version: 0.14.0 (or another approved, unpublished 0.x version)
- publish: true
- confirm: REPLACE_PYTHON_MARKATA_WITH_GO
- Approve the pypi environment gate.
Check the resulting PyPI release and test a new python -m venv with python -m pip install markata and markata version.

The publish job is a separate, minimal-permission job using PyPA pypa/gh-action-pypi-publish and short-lived OIDC tokens. Pull requests, manual dry-runs, and non-main branches never publish. An explicit confirmation string and GitHub environment gate prevent accidental uploads.

Freeze the Python repo’s old manual PyPI release workflow as part of the handoff so a future Python release does not retake the latest PyPI version. It currently needs owner attention because GitHub rejects branch creation in WaylonWalker/markata-py. Do not reuse its existing pypi_password secret.

Compatibility consequences #

Users needing the historical Python library should pin the last Python release in a separate environment: python -m pip install markata==0.10.0. This is not the Go executable and is not a maintained 0.x Go release.
import markata from a new Go wheel is only a tiny binary-launching wrapper; it is not API compatible with old Python Markata plugins.
Existing Go binaries, markata-go entry points, Kubernetes Helm settings, and Go GitHub releases are unchanged by this PyPI handoff.
On unsupported Python/platform/architecture combinations, pip may select an older Python release rather than the Go wheel. The eight-wheel matrix must be checked before making blanket cross-platform promises.
No stable Go 1.0 release or repository version tag is required.

This release is an explicitly authorized new PyPI packaging path, distinct from the earlier GitHub repository rename. The version is chosen on dispatch.

Current installation status #

The PyPI handoff has occurred: current markata releases install the Go CLI after a version break from the Python implementation. Historical Python wheels remain immutable and can be pinned. This handoff does not imply Python API compatibility. The release preparation steps above document the transition process, not the present installer identity.

Fast PR gate rollout

2026-10-31T00:00:00Z

Tracking issue: #1747.

Current stage: shadow validation #

The new Fast PR validation workflow provides an always-present PR Gate job on pull requests, pushes to main, merge groups, and manual dispatch. It runs alongside existing CI; do not replace any required check or weaken release gates until the new check has been observed.

PR classification is intentionally conservative:

Only changes confined to docs/**, docs-site/**, README.md, or CONTRIBUTING.md qualify for the docs-only Go-test exemption. The existing documentation-site workflow still validates relevant documentation changes.
All other changes check gofmt on changed Go files, run a CLI build and smoke check, and go test -short ./... with the explicitly observational Build Lab characterization excluded.
Python-related source/packaging changes also run python/tests unit tests.
Main pushes, merge-group checks, and manual runs receive the broad path.
Failure to classify changed files is an error; unknown paths are not considered documentation-only. Patch whitespace is always verified.
Use the stable job name PR Gate (not the workflow name) for rulesets.

The full Linux race/coverage shards, macOS/Windows matrix, and specialized browser/packaging checks continue to run under existing workflows. The Docker PR job no longer repeats a separate go test ./...; Docker image build and smoke tests remain in place, and publishing still tests source before advancing images.

Observed baseline: 2026-10-29 through 2026-10-31 #

Queried the repository’s completed Actions runs through October 31, identified 91 completed pull-request runs of the CI workflow (47 cancelled, 32 successful, 11 failed, and 1 other conclusion), then selected the latest 25 non-cancelled runs for latency statistics. The sample is 19 successes and 6 failures; cancelled runs are excluded from latency percentiles, not silently treated as successes.

Wall time uses workflow updated_at - created_at (an approximation which can include rerun elapsed time); job runtime uses completed_at - started_at. Nearest-rank percentiles are reported in seconds, rounded to the nearest second.

Measure (25 sampled PR CI runs)	p50	p90
CI workflow wall time	323s (5m23s)	445s (7m25s)
Windows short tests	257s	409s
macOS short tests	118s	140s
Linux core race/coverage	264s	270s
Linux CLI/search race/coverage	273s	287s
Linux site integration race/coverage	280s	312s
Lint	186s	195s

Windows has the largest p90; Linux site/CLI also contribute substantially to the critical path. Do not assume Windows is always the bottleneck. The sample’s longest observed CI wall time was 1307s, associated with a rerun. One rerun exposed inconsistent job scheduling timestamps; do not subtract job creation times to claim accurate runner queue time without verifying the run attempt and dependency waits.

Representative runs: recent success, Linux + Windows comparison, slow rerun.

This baseline measures the existing CI workflow, not the newly introduced PR Gate. Repeat the same sample method after its deployment; add separate runner queue and dependency-wait metrics from attempt-specific timestamps.

Baseline and progression #

Before switching branch protection, record at least 20 completed, non-cancelled PR runs with each workflow’s wall time (created to completion), queue delay, job-level duration, pass/fail and critical path. Report p50/p90, not only the fastest run. Report cancelled runs separately because frequent commits can bias the successful sample. Include a mix of docs, Go, frontend and packaging PRs.

Shadow: Compare PR Gate against the existing CI check. Investigate any disagreement (especially tests skipped by -short).
Gate migration: After evidence is accepted, make only PR Gate and relevant focused checks required. Keep the broad matrix on main and nightly. Coordinate the change with the existing CI specification.
Release hardening: Validate immutable SHAs and artifacts before any stable publishing or promotion. Preserve the existing release/test/sign/SBOM checks throughout the transition.

GitHub configuration (maintainer action) #

The workflow itself cannot configure repository branch protection. When ready: protect main with PR Gate as a required check, require a current branch or merge-queue validation, and forbid bypasses. Do not drop old required checks until both are green on real PRs and the policy change has been reviewed. For merge queue, merge_group is already subscribed.

Rollback #

Restore the existing required check set and disable/remove pr-fast.yml in a small revert PR. Docker source tests on actual publication are unchanged. Never roll back by bypassing a failed release test or forcing a publication.

Editor workspace file tree

2026-10-30T00:00:00Z

Start the Go editor for a cloned site:

markata editor --workspace ~/git/my-site --port 8002

For the Python example, set MARKATA_LSP_WORKSPACE to the same site directory before starting examples/fastapi_editor.py.

The Files tree lists content discovered by Markata’s glob plugin. The editor reads markata-go.toml, YAML, or JSON configuration from the selected workspace. It uses the configured glob patterns and gitignore behavior. Without a config, it discovers Markdown under pages/ and posts/ with Markata’s defaults. The Feeds view groups posts selected by configured feed filters. The Tags view groups loaded documents by their frontmatter tags. The selector shows each view’s count.

Select a file to load its original source, including frontmatter. Edit it and view the Go-rendered preview. The Go workbench saves selected Markdown files to the site after a short pause and keeps a browser recovery copy. Scratch drafts and imported files stay in browser storage. Use the command palette to export the active file or import a Markdown file. The scratch draft.md buffer remains available for imported documents.

Only discovered files inside the selected workspace can be read or written. Files reached through symlinks outside the workspace are excluded. Reads and writes are limited to 200,000 bytes; a failed read or save leaves the current editor buffer intact.

API usage #

Go applications can use editorworkspace.New(root), Files(), Read(path), and Write(path, source) from github.com/WaylonWalker/markata/pkg/editorworkspace. Discovery uses the existing glob and load plugins without running a site build.

Python applications can use the same implementation through the bundled binary:

from markata import workspace_files

listing = workspace_files("/path/to/site")
source = workspace_files("/path/to/site", path="posts/hello.md")["source"]

The CLI exposes the JSON interface as markata workspace --workspace /path/to/site and markata workspace --workspace /path/to/site --file posts/hello.md.

The Go and FastAPI servers provide GET /workspace and GET /workspace/file?path=posts/hello.md. The Go server also accepts PUT /workspace/file?path=posts/hello.md for autosave. The browser loads source on demand. See the Go editor guide and Python editor guide.

Site defaults #

When the selected workspace has a config, the editor applies its palette, light/dark fallback, aesthetic, fontpack, text size, palette variables, custom CSS, and Markdown highlighting settings. Local palettes/ and aesthetics/ catalogs resolve from that workspace, as does an explicit fontpacks_file. Saved browser appearance preferences take priority over site defaults. The preview remains an article preview; it does not run page templates or a site build.

Python hosts can pass workspace="/path/to/site" to appearance(), render(), and render_async(). The JSON command equivalent is markata render --workspace /path/to/site --json (Markdown on stdin), or markata render --workspace /path/to/site --appearance for controls and assets.

The editor first discovers paths and opens the selected source. Titles, tags, and feed membership load afterward in the background. The Tags view becomes available when metadata is ready and builds its tree when opened. Metadata errors do not block editing. Use markata workspace --paths --workspace PATH or workspace_files(PATH, metadata=False) for discovery without parsing documents. Server clients can request GET /workspace?metadata=true when they need metadata.

If the workspace contains a real draft.md, the scratch buffer appears as Unsaved draft.md (or a numbered variant if that name also exists). Imports open the scratch buffer, and real workspace files retain their own browser drafts.

Reuse server state #

The Go editor retains discovered paths and parsed document metadata for its workspace. Repeated file requests check cached membership and read only the selected source. The server reuses its Markdown renderer until the site configuration changes. Browser LSP sessions share parsed workspace data and keep unsaved documents private.

A filesystem watcher refreshes changed documents after a short delay. Configuration and appearance changes refresh the renderer on its next request. A periodic scan recovers missed filesystem events. The Files, Feeds, and Tags trees refresh when you reload the browser page.

Reopening a file or reloading the page loads its latest disk content if its browser draft has no edits. If the draft has edits, the editor preserves them. A warning identifies disk changes when the saved draft has a source version. Older saved drafts remain intact during migration. The Go workbench automatically saves edits to selected workspace Markdown files. Scratch drafts and imports stay in browser storage until you export them. The browser retains a recovery copy if a site save fails.

Go hosts can open retained state with editorworkspace.Open(ctx, root). Use Paths(), Files(), Read(path), and Snapshot() for cached access. Call Close() when the host stops, or cancel the parent context. The existing editorworkspace.New(root) and Python helpers keep their one-shot behavior.

Renderer integration benchmarks

2026-10-29T00:00:00Z

These measurements use existing repository fixtures with the FastAPI editor. The benchmark includes the exact post that BenchmarkBuild_Incremental edits: benchmarks/site/posts/blog/2024/01/post-001.md. The other cases come from rendering-fixtures/; they are visual regression fixtures, rather than existing performance benchmarks.

Fixture coverage #

File	Coverage
`post-001.md`	Deterministic site benchmark post, including code
`home.md`	Small page with minimal assets
`markdown-chart-fallback.md`	Chart.js output and accessible data fallbacks
`md-card-headings.md`	Cards and expressive headings
`roads.md`	Roads, layout styles, and initialization script
`story-layout.md`	Longer structured page
`test-headings.md`	Heading syntax and typography

Inputs retain their complete file contents, including frontmatter. These calls measure the standalone renderer; they do not run the site build pipeline or its frontmatter loading stage.

Measured timings #

All values are milliseconds. The Go column shows the median of three benchmark runs. The other columns show medians across 15 calls, except the final column.

Fixture	Input bytes	Go renderer	Python render call	FastAPI render timer, edit	HTTP edit	HTTP edit p95
`post-001.md`	1,518	3.05	137.51	135.02	136.25	148.45
`home.md`	426	0.40	128.50	128.24	129.15	136.19
`markdown-chart-fallback.md`	1,550	33.04	476.93	260.01	264.50	470.84
`md-card-headings.md`	1,104	0.89	151.58	152.03	153.45	167.69
`roads.md`	1,598	1.08	139.34	174.50	177.22	224.00
`story-layout.md`	3,900	1.46	156.73	153.57	154.97	174.24
`test-headings.md`	1,245	0.82	168.01	151.57	152.70	170.24

For the existing site benchmark post, Go rendering takes about 3 ms, while a Python render call takes about 138 ms. The Python API starts a Go process for each call and decodes its JSON output. The gap includes process initialization, serialization, pipe transfer, and Python decoding; these measurements do not isolate each part.

Chart.js has higher rendering and transfer costs because its response includes vendored JavaScript and generated initialization code. The current fragment response still sends those feature assets with each chart edit. Keeping shared CSS loaded does not remove all repeated feature-asset bytes.

Initial document versus later edits #

Response sizes below are uncompressed JSON body bytes, rounded to KiB (1,024 bytes). They exclude HTTP headers and separately requested appearance assets. Initial requests include a full document; edit requests set include_document to false.

Fixture	Initial HTTP median, ms	Edit HTTP median, ms	Initial response, KiB	Edit response, KiB	Fewer response bytes
`post-001.md`	135.39	136.25	46.44	20.01	56.9%
`home.md`	130.10	129.15	8.13	0.86	89.4%
`markdown-chart-fallback.md`	432.89	264.50	460.25	226.92	50.7%
`md-card-headings.md`	136.74	153.45	45.55	19.57	57.0%
`roads.md`	167.05	177.22	93.22	43.40	53.4%
`story-layout.md`	152.85	154.97	25.48	9.54	62.6%
`test-headings.md`	154.95	152.70	13.25	3.42	74.2%

Omitting the document shell reduces response bytes in every fixture. It does not establish a latency improvement: each mode runs separately, and host load varies between modes. Some fragment requests therefore take longer despite their smaller responses.

Timing boundaries and limits #

Go renderer: RenderStandalone setup, Markdown processing, asset generation, and inline tag generation. Fixture reads occur before timing starts.
Python render call: synchronous render(..., inline_assets=True, unsafe=True), including process startup, output transfer, and JSON decoding.
FastAPI render timer: asynchronous render_async(...), including process startup and JSON decoding. Document construction and HTTP response encoding occur afterward.
HTTP time: request object construction, a new localhost connection, FastAPI processing, response transfer, and body reading. Request JSON encoding and response JSON decoding are excluded.

Each Python and HTTP mode has two excluded warm-up calls and 15 measured calls per file. Every render still starts a fresh Go process; these are warm filesystem measurements, rather than a persistent renderer process. The nearest-rank p95 equals the maximum with only 15 samples. Use more samples for stable tail-latency decisions.

The measurements ran sequentially on a shared workstation with normal background activity. They are observations from this host, rather than service limits or a controlled before-and-after experiment. They exclude the editor’s 350 ms debounce, browser layout, chart drawing, Mermaid execution, and user-perceived paint time. No site build cache, encryption key, or site configuration participates in these standalone calls.

Environment and raw results #

Date: 2026-10-29 UTC.
Source revision: f226485ead9f91081e2eb3c848b3290bf1df040a.
CPU: AMD Ryzen 5 3600, 6 cores and 12 logical CPUs.
OS: Linux-7.2.8-9-omarchy-x86_64-with-glibc2.44.
Go: go1.26.3 linux/amd64.
Python: 3.13.13.
FastAPI: 0.162.0; Uvicorn: 0.54.0.

The JSON report contains every measured sample, fixture SHA-256 hashes, and the installed binary and wrapper hashes. The Go benchmark output contains iteration counts, allocation counts, and all three runs.

Reproduce #

Use a virtual environment with the current Markata wheel, FastAPI, and Uvicorn. Run these commands from the repository root, sequentially:

python python/benchmark_editor.py
go test ./pkg/plugins -run '^$' -bench '^BenchmarkRenderStandaloneFixtures$' -benchtime=200ms -count=3

The Python script starts a temporary localhost server and stops it when the run ends. It writes benchmarks/renderer-integration-YYYY-MM-DD.json using the UTC date. It does not replace the live editor server.

Before comparing changes, keep the fixture bytes, dependency versions, machine, and renderer options the same. Compare medians and raw samples as well as response sizes. Useful next measurements include process initialization, JSON encoding, asset transfer, browser paint, and memory retained after repeated diagram edits.

Go server workbench #

The Go workbench uses the same seven fixture files and the same HTTP timing boundaries. All fixture hashes match the Python report above. The server renders directly in process and keeps one previous result in memory.

Each mode uses two excluded warm-up calls and 15 measured calls. Before every cache-miss call, a separate unmeasured request renders a small invalidator document. This keeps the measured fixture bytes unchanged while preventing an accidental cache hit. Every measured response checks its cached field. Cached edits use the same source repeatedly without invalidation. The invalidator request is excluded from the HTTP time and response size.

HTTP results #

Values are milliseconds. Each median and p95 comes from 15 calls. The Python column comes from the earlier report; the Go columns come from a separate run on the same workstation.

Fixture	Python HTTP edit median	Go initial miss median	Go edit miss median	Go edit miss p95	Go cached edit median
`post-001.md`	136.245	2.247	2.143	3.599	0.365
`home.md`	129.152	0.645	0.466	0.867	0.324
`markdown-chart-fallback.md`	264.495	36.032	28.571	53.724	0.295
`md-card-headings.md`	153.448	0.799	1.504	1.790	0.366
`roads.md`	177.217	0.957	0.973	1.547	0.325
`story-layout.md`	154.968	1.368	1.326	1.827	0.300
`test-headings.md`	152.701	0.838	0.805	1.721	0.293

For the site benchmark post, an uncached Go edit takes 2.143 ms over loopback HTTP. A repeated cached edit takes 0.365 ms. The earlier Python HTTP measurement for that exact file is 136.25 ms.

The Go server avoids a renderer subprocess per request. It also links feature assets instead of embedding their contents in each response. Both differences contribute to the observed gap. These runs do not isolate language or process-startup costs. The native Go renderer benchmark uses inline assets, so it can take longer than the Go HTTP path with linked assets.

Response sizes #

Values are uncompressed JSON body KiB. Separately requested stylesheets, libraries, and fonts are excluded. Initial responses contain a complete document and fragment fields. Edit responses omit the document.

Fixture	Python edit response	Go initial response	Go edit response	Go initial-to-edit reduction
`post-001.md`	20.01	24.62	8.82	64.2%
`home.md`	0.86	8.99	1.02	88.6%
`markdown-chart-fallback.md`	226.92	24.15	8.54	64.6%
`md-card-headings.md`	19.57	12.99	2.99	77.0%
`roads.md`	43.40	19.58	6.30	67.8%
`story-layout.md`	9.54	30.59	11.82	61.4%
`test-headings.md`	3.42	16.24	4.65	71.4%

The Go editor retains loaded libraries and shared styles in the preview frame. The linked-asset policy makes its chart response smaller, but the browser must fetch each dependency when it is first needed. Response-size reductions do not include those initial asset transfers and do not establish a browser paint-time improvement.

Go measurements and reproduction #

The Go run uses runtime source revision 059bb011f3314c43ca9e0c6e51d7ed735cf68790. The merged parent adds benchmark tooling and documentation without changing that runtime. The host is the same AMD Ryzen 5 3600 workstation, with 12 logical CPUs and Go 1.26.3. The Go HTTP client uses Python 3.14.8; the earlier Python-reference client uses 3.13.13. The comparison includes that client-version difference. The JSON report records its timestamp, OS, binary hash, and harness hash.

The Go server timer includes rendering, asset registration, and optional document construction. It excludes HTTP JSON encoding and network transfer. The Python server timer above excludes document construction. Use HTTP measurements to compare the complete request paths.

These are sequential measurements on a shared workstation, rather than a controlled before-and-after experiment. They exclude server startup, appearance generation, cache invalidation calls, separately fetched assets, editor debounce, browser layout, and drawing. The Go editor debounce is 250 ms. The p95 equals the maximum with 15 samples; larger runs are needed for stable tail estimates. No site configuration, site build cache, encryption keys, or site lifecycle stages participate.

The Go HTTP report contains every sample and fixture/binary/harness hashes. The native Go output contains three fresh runs of the parent’s renderer benchmark on the same fixtures.

Run these commands sequentially from the repository root:

go build -o /tmp/markata-workbench-benchmark ./cmd/markata-workbench
python python/benchmark_go_editor.py --binary /tmp/markata-workbench-benchmark
go test ./pkg/plugins -run '^$' -bench '^BenchmarkRenderStandaloneFixtures$' -benchtime=200ms -count=3

The standard-library Python client starts a temporary Go server on an OS-assigned loopback port and stops it after the run. It does not restart the live editor or change its cache. Use --samples, --warmups, and --output to control the run. The default output uses the UTC date.

Browser WASM worker #

Start the WASM demo before the benchmark:

python3 scripts/wasm-workbench.py --serve

In another terminal, run:

uv run --with playwright python scripts/benchmark-wasm.py --output /tmp/wasm-benchmark.json

Use --url for a different demo address. Install Playwright Chromium if the browser is unavailable. The benchmark uses the same seven fixtures as the HTTP clients. Each fixture uses a fresh worker, two excluded warmups, and fifteen measured renders. The report includes raw samples, fixture hashes, browser version, median, and p95.

These timings measure worker rendering. They exclude worker startup, message transfer, layout, and paint. Do not compare them directly with HTTP request timings.

Local demos use these addresses when all three run together:

Python/FastAPI: http://127.0.0.1:8765/
Go server: http://127.0.0.1:8767/
Browser WASM: http://127.0.0.1:8766/

Integration verification on 2026-10-29 #

Fresh reports use the *-suite-2026-10-29.json names for Python and Go. The WASM report is benchmarks/wasm-workbench-2026-10-29.json. For post-001.md, the Python HTTP edit median was 149.282 ms. The Go HTTP edit median was 2.389 ms; the cached median was 0.301 ms. The WASM worker median was 10.9 ms. These measurements use different timing boundaries and asset policies, as described above.

Shared editor features and runtime differences #

All three demos provide the same editor features:

System typography, appearance controls, and Default/Vim/Emacs/Sublime keymaps.
Open .md import and Download .md export.
Automatic draft recovery and visible save status.
Live previews with a 250 ms edit debounce and protection against stale results.
A 200,000 UTF-8 byte limit, with errors that preserve the current draft.

An oversized import leaves the current draft intact. Download the draft before clearing browser storage. If storage is unavailable or full, editing and downloads remain available, but drafts cannot survive closing the page. Each origin stores its own draft and appearance settings. Different ports do not share these settings. For a font comparison, select the same font pack and text size in each demo. The default uses system fonts; operating systems can display different system typefaces.

Runtime behavior	Python / FastAPI	Go server	Browser WASM
Rendering location	Server subprocess per request	Directly in Go server	Persistent browser worker
Markdown transfer	HTTP to local server	HTTP to local server	No render request
Rich feature assets	Inline response assets	Linked assets reused by browser	Bundled assets cached locally
Offline reload	Requires running server	Requires running server	Available after Ready offline
Authored raw HTML	Enabled inside sandbox	Enabled inside sandbox	Disabled
Repeated source	New renderer process	Last result cache	Persistent renderer runtime

Runtime differences do not require different fonts, import controls, or draft feedback. Raw HTML and cache policies are demo choices, rather than requirements of Python, Go, or WASM. All previews use a sandbox. Authored external images and links can still access the network. These demos render standalone Markdown; they do not load a site’s configuration or run its complete build lifecycle.

Editor Command Palette

2026-10-29T00:00:00Z

Select Commands above the Markdown editor, or press Ctrl+Shift+P. On macOS, press Cmd+Shift+P. Ctrl/Cmd+K also works. The dialog is titled Command Palette and works with the Default, Vim, Emacs, and Sublime keymaps. In the Go workbench, Ctrl/Cmd+P opens the fuzzy file finder.

Search for a command, such as callout, diagram, or highlight. Use the arrow keys to choose a result, then press Enter. You can also select a result with a mouse or touch. Each result shows the syntax that it inserts.

For example, the Note box command inserts:

!!! note "Note"
    Write your note here.

The editor selects the placeholder so you can replace it immediately.

In the Python and Go browser editors, the connected language service also completes container classes and modifiers from these commands. For example, type ::::: md-i to suggest md-icon. Inside its attribute block, type {data-s to suggest data-size, then type data-size=" to choose sm or lg.

Inside a Mermaid fence, the language service suggests diagram types such as flowchart, sequenceDiagram, and classDiagram; flowchart directions; a flowchart starter; and Mermaid class style properties. Press Ctrl+Space to show completions at the cursor. The WASM editor keeps the full command palette and does not currently connect to the LSP. If you select text before opening Commands, the command uses that text instead. For example, Highlighted text changes selected important to ==important==. Named Lucide icon commands replace selected text with the chosen icon. Block commands add blank lines around their output to keep surrounding paragraphs separate. Multiline selections receive the indentation required by admonitions. Commands use the primary selection when the editor has multiple selections.

Use the editor’s normal undo command to remove an insertion in one step. The existing draft saving and preview update run after insertion. Press Escape, select Close, or click outside the dialog to cancel. The editor keeps your text and selection and receives focus again.

The catalog includes 110 authoring snippets and all 2,118 icons in the bundled Lucide pack. Search matches command names, syntax hints, and aliases. The palette shows up to 60 results at once. Refine the search to find more specific commands. For example, search Lucide: zodiac-aries to find that icon directly.

Family	Commands
Admonitions	All documented types, closed and expanded disclosures, and split columns
Roads	Winding, timeline, steps, snake, cycle, constellation, git, and editorial; story and reveal variants
Cards and layouts	Card, box, layout, columns, grid, rail, pending cards, stack, divider, connector, and story section
Icons and feature rows	Icon tile, icon feature row, generic Lucide shortcode, every bundled Lucide icon, and custom icon-pack shortcode
Metrics	Status, statistic, delta, native meter, and progress gauge
Interactive content	Checklist and Markdown source disclosure
Mermaid	Flow, sequence, class, state, entity relationship, Gantt, pie, mind map, timeline, and git diagrams
Chart.js	Bar, line, area, stacked bar, pie, doughnut, scatter, bubble, radar, and polar area
Web Awesome	Comparison, details, tabs, copy button, QR code, badge, tag, tooltip, carousel, animated image, and raw component template
Inline extensions	Highlight, keyboard keys, emoji, superscript, subscript, attributes, footnote, and definition list
Images and citations	Captioned figure, image URL, and attributed quotation
Site features	Wikilink, post embed, external embed card, YouTube embed, hover cards, table of contents, glossary frontmatter, and contribution calendar
Standard Markdown	Table, task list, code fence, inline code, bold, italic, strikethrough, and link

Preview and site requirements #

The palette uses local assets in all three workbenches. It remains available offline after the WASM workbench caches its assets. Bundled Lucide icons, roads, article containers, metrics, Mermaid, and Chart.js render in the standalone preview.

Commands for site features state their requirements in the result description. The standalone renderers do not load a site content index or the Web Awesome plugin and custom-element runtime. Web Awesome commands insert the documented Markdown shortcuts for a configured site build. They do not load third-party scripts in the standalone preview. The raw component template supports components that have no Markdown shorthand. Replace its tag with the required Web Awesome tag.

Wikilinks and post embeds need site content. External embeds need the site embed pipeline. Hover cards and contribution calendars need their site plugins or runtime assets. Custom icon packs need site configuration and local SVGs. The TOC command inserts [[toc]] for the site table-of-contents plugin. Use glossary frontmatter at the start of a new glossary post. Replace sample image paths and IDs before publishing.

Try a complete example #

Open the workbench with ?example to load the sample in the editor and open the command palette. For example, visit http://localhost:8766/?example for the Go workbench. In the Go workbench, use the Open Markdown file command to import examples/command-palette-showcase.md as a scratch draft. The example combines icon cards, a steps road, a feature row, metrics, Mermaid, and a Chart.js chart. It also shows Web Awesome source with its site requirement clearly identified. The chart data is illustrative.

See the Markdown guide, container guide, roads guide, icon guide, and Web Awesome guide for syntax details. The editor comparison explains runtime differences.

Browser WASM renderer and local workbench

2026-10-28T00:00:00Z

Build and serve the workbench from the repository root:

python3 scripts/wasm-workbench.py --serve

Open http://127.0.0.1:8766/. Go and Python 3 are build requirements. The browser downloads the Go runtime once. No Python package, Node build, CDN, or rendering API is required. Port 8765 remains available for the FastAPI editor.

Write Markdown on the left and read its preview on the right. The editor supports Vim, Emacs, Sublime, and default keymaps. Use the appearance picker to change the palette, aesthetic, fonts, and text size.

Use Open .md to import a document. Use Download .md to export it. The document limit is 200,000 UTF-8 bytes. The footer reports render time and draft storage status. A storage error does not stop editing or export.

Drafts and offline use #

Drafts and keymap preferences stay in browser storage. Drafts use a separate key from the FastAPI editor. On first use, the workbench can copy that editor’s draft when both apps share an origin. Different ports have separate storage.

Wait for Ready offline before disconnecting. The service worker saves the app, WASM renderer, editor, theme assets, and fonts. You can then reload the page and continue editing without a network connection.

Browser storage can be cleared or evicted. Private browsing can restrict it. Export files to keep durable copies. The demo edits one document at a time; it does not sync drafts between devices or resolve edits from multiple tabs.

Markdown stays on the device. External images and links in authored content can still contact their destinations. Raw HTML is disabled. The preview runs in a sandbox with a separate origin and cannot read the editor’s storage.

Use the worker in another app #

Build the static files, then copy the generated directory to your host:

python3 scripts/wasm-workbench.py --output /tmp/markata-browser

The generated worker.js, wasm_exec.js, and markata.wasm form the rendering entrypoint. Keep these files together. The build copies wasm_exec.js from the Go installation that builds the module.

const worker = new Worker('./worker.js');
worker.onmessage = ({data}) => {
  if (data.type === 'ready') {
    worker.postMessage({source: '# Hello from Markata', revision: 1});
  } else if (data.type === 'result') {
    if (data.result.error) console.error(data.result.error);
    else console.log(data.result.html, data.result.assets, data.render_ms);
  } else if (data.type === 'fatal') {
    console.error(data.error);
  }
};

The result follows the standalone renderer’s schema version 1. It includes HTML, feature flags, ordered assets, and head/body tags. Bundled assets contain IDs rather than their file contents. Serve those files from appearance/. Generated initializer scripts retain their contents. The sample parent app loads each dependency once. It sends cached asset contents to the sandboxed preview.js, which disposes old Chart.js instances.

Inside the initialized runtime, markataRender(source) returns a JSON string. Invalid argument types, oversized documents, and render errors return an error field. The worker preserves the request’s revision. Hosts must discard stale results. Keep one render in flight and replace pending edits with the latest source. The sample editor uses a 250 ms debounce.

The renderer uses the same Go Markdown implementation as the Python API. It supports syntax highlighting, admonitions, containers, bundled Lucide icons, Mermaid, and Chart.js. Site discovery, frontmatter processing, feeds, and site-dependent plugins require a full Markata build. Mermaid runs in client mode.

Static hosting #

Serve the output over HTTPS or loopback HTTP. Service workers do not work from file:// URLs. Subdirectory hosting is supported; keep relative paths intact.

Serve .wasm as application/wasm. The loader also supports hosts with an incorrect MIME type. Enable gzip or Brotli compression. The generated .gz files require Content-Encoding: gzip and the original file’s content type. The Python server handles these headers automatically.

The parent app reads assets from its service-worker cache. It embeds preview fonts and styles so the isolated preview can render offline. The included server also sets CORS headers for hosts that reuse these assets. Keep sw.js available for revalidation. Each build gives its offline cache a content-derived version. A new version activates after its complete asset bundle is cached. Reload the tab to use a newly installed version.

The initial module is larger than a JavaScript-only Markdown parser because it includes Go, Chroma syntax highlighting, and Markata’s extensions. On the local benchmark build, gzip reduced the module to about 6.5 MiB. Subsequent renders reuse the runtime and parser. The worker keeps editing responsive.

To serve an existing build:

python3 scripts/wasm-workbench.py --output /tmp/markata-browser --no-build --serve --port 8766

Stop the server with Ctrl+C. To remove an offline copy, unregister its service worker and clear its site data in browser settings. Export the draft first.

Browser checks #

python3 scripts/wasm-workbench.py
uv run --with playwright python -m playwright install chromium
uv run --with playwright python tests/wasm/test_workbench.py

The checks cover offline reload, import/export, draft recovery, rapid edits, repeated diagrams and charts, keymaps, mobile width, storage failures, input limits, worker errors, and local-only network requests. Warm-render measurements are reported without machine-specific timing assertions.

Shared editor behavior #

Use Open .md to import a Markdown file. An oversized file leaves the current draft intact. Use Download .md to keep a copy outside browser storage. The footer reports whether the draft was saved. Storage failures leave editing and downloads available. See shared editor features and runtime differences for the comparison.

Insert Markdown commands #

Select Commands or press Ctrl+Shift+P (Cmd+Shift+P on macOS). Search for special syntax, then press Enter to insert it at your selection. See the command palette guide for the catalog and keyboard controls.

Open the workbench with ?example to load a Markdown example and open the command palette.

Live Markdown editor with Go

2026-10-28T00:00:00Z

Run the shipped Go editor command:

markata editor --workspace ./docs

Open the local URL printed by the command. Edit Markdown on the left and view the preview on the right. Press Ctrl+C to stop the server. The default address is 127.0.0.1:8766. For a checkout build, run go run ./cmd/markata-go editor --workspace ./docs.

The Go server calls Markata’s standalone renderer directly. It starts no Python process and needs no WASM runtime. It uses the same Markdown renderer as the Python API and FastAPI editor. The preview does not build a site. The language service indexes Markdown and reads workspace configuration for existing mention support.

Use the appearance picker to select a palette, color mode, style, font, or text size. Open Editor settings to choose line wrapping, keymap, and layout. Drag the divider between the source and preview panes to resize them. Choose Editor only or Preview only to focus on one pane; Editor and preview restores the split. Scrolling either pane keeps the corresponding Markdown visible in the other. When you write or move the cursor, the preview follows the editor. Scroll sync is on by default; turn off Sync editor and preview scrolling in Editor settings to scroll each pane independently. The choice is saved in this browser. At the end of a document, both panes keep extra scroll space so the last lines can move above the bottom edge while you write. In split view, a subtle marker shows the corresponding preview block, with a thin caret and You flag at the active location. When rendered text matches the source line, the preview caret follows the character cursor. For content that a renderer transforms or replaces, it falls back to the nearest mapped source position. Click rendered text to move the source caret to the matching text when possible; links keep their normal navigation behavior. The source pane keeps its normal caret on the actual text cursor. With the Vim keymap, the preview caret changes shape for normal, insert, replace, and visual modes. Preview updates preserve unchanged blocks, and layout changes refresh the source-to-preview mapping, including after images and fonts load. While you edit, the preview follows the caret after the matching content update completes, including when you keep typing on the same line. Scroll changes caused by a render or a delayed image/font layout are not mistaken for manual scrolling. The preview marker is subtle and marks the rendered block for the current caret line. Nested Markdown container boundaries add source anchors to improve scroll alignment in long sections; these markers exist only in the preview render and do not change your source. Within nested content, the marker follows the narrowest container that contains the caret line. Choose Default, Vim, Emacs, or Sublime keymaps in Editor settings. In Vim mode, press / to search forward, ? to search backward, then n or N to move between matches. Code highlighting, icons, admonitions, tables, checklists, Mermaid, and Chart.js use local assets.

Press Ctrl+P (Cmd+P on macOS) to find a site file by its path, title, slug, or tag. The finder shows the current and recently opened files when its search is empty. Select a result or press Enter to open it in the editor. Choose Feeds or Tags in the workspace selector to browse posts by feed or tag. Feed names are shown as roots with folders relative to the workspace.

Edits to selected site files save back to the workspace after a short pause. Unsaved scratch documents stay in browser storage. The browser also keeps a recovery copy of workspace edits. Use Ctrl+Shift+P and search for Download current file to export a copy, or Open Markdown file to import a file as an unsaved draft. A storage error appears beside the render metrics. Editing and downloads remain available. The server writes only selected workspace files. Scratch drafts remain local to the browser origin, so drafts on one port remain separate from drafts on another. Workspace saves and new-post creation require a same-origin browser request. The server rejects missing or foreign origins before it changes a site file.

The preview updates after a 100 ms pause. One request runs at a time, and newer edits replace pending edits. Old responses cannot replace a newer draft. Errors preserve the last successful preview. The footer shows Go render time, total edit-to-preview time, source size, and preview size. Repeated source uses a one-entry memory cache. Appearance changes update the preview without a render request. Workspace post embeds in  ![[post-slug]] or ![embed](path/to/post.md) format render as cards linked to the matching site post. Fenced code examples remain literal source.

Language assistance #

The editor connects to the existing Markata LSP through /lsp over WebSocket. The server indexes the directory from --workspace. The default directory is the current directory. The browser LSP accepts same-origin connections on localhost or a loopback IP only.

Type [[ for wiki-link suggestions, including aliases. Type [label]( for Markdown document paths. Automatic suggestions wait for a short typing pause. Press Ctrl+Space to request suggestions immediately at the cursor. Use the arrow keys and Enter to select a suggestion. Existing frontmatter, admonition, and mention completion also use the LSP. Broken wiki links receive an underline. The underline tooltip shows the diagnostic message. The workbench preview resolves valid [[wikilinks]] against the site’s workspace index. Click a resolved wikilink in the preview to open that post in the editor. Select the error and warning counts in the bottom status bar to inspect diagnostics and jump to their source locations.

The editor sends unsaved text as a synthetic .markata/browser-draft.md document. This document stays in memory. Markdown path suggestions start at the workspace root because the draft has no source file. The Files tree opens source files from the selected workspace using Markata glob rules. The Feeds view groups files by configured feed filters, and the Tags view groups them by loaded frontmatter. The selector shows file, feed, and tag counts. See workspace navigation. Each WebSocket connection owns its own draft and index. Reload the page to index external file changes.

Edit page properties #

Select a site file, then choose Properties to edit its frontmatter in the full-height page-details view. The live preview stays visible beside it. Choose Back to Markdown to return to the source, or Edit YAML to work directly with the frontmatter block. Press Escape to return to the article. The command palette also has actions to open page details, add a property, and return to Markdown.

The page summary shows the title, URL slug or source path, and publication state. Common fields appear first. Choose Add property, search for a known field, and select it. Open Custom property to add a site-specific YAML field. Edit tags as chips: remove one tag at a time or enter a tag and choose Add. Advanced fields remain available under Show advanced properties.

Property edits update the Markdown source and use the normal workspace save and preview behavior. Press Ctrl+Z or Cmd+Z to undo an edit. Use Remove to delete a property from the page.

The footer reports the language connection state. Editing and preview continue if the connection fails. Reload the page to reconnect. The browser adapter is shared with the FastAPI example.

For an embedded application, use workbench.NewWithWorkspace(ctx, root). Cancel ctx during shutdown to close active language connections. workbench.New() uses the current directory and the lifetime of the application.

WebSocket protocol #

GET /lsp/config returns rootUri and documentUri for the selected workspace. Connect to /lsp with the page origin. Each WebSocket text message contains one JSON-RPC object. WebSocket messages omit the stdio Content-Length headers. Send initialize, initialized, and textDocument/didOpen before language requests. The session accepts the synthetic draft URI from the configuration response. The server ignores browser workspace-change notifications and overrides the client workspace during initialization.

Browser completion responses contain at most 200 suggestions. More specific text requests a new list. Messages have a 2 MiB limit. A disconnect releases the session. The endpoint rejects missing or foreign origins. It provides no authentication or shared workspace management. Keep this example on a trusted local address.

Embed the handler #

Mount the handler at the root of a dedicated origin:

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/WaylonWalker/markata/pkg/workbench"
)

func main() {
    handler, err := workbench.New()
    if err != nil {
        log.Fatal(err)
    }
    server := &http.Server{
        Addr: "127.0.0.1:8767", Handler: handler,
        ReadHeaderTimeout: 5 * time.Second,
    }
    log.Fatal(server.ListenAndServe())
}

Create one handler at startup. It prepares the shared appearance bundle once. The handler owns no listeners, signal handlers, or application configuration. A future builder can embed it without the demo command.

Render API #

curl http://127.0.0.1:8767/render \
  -H 'Content-Type: application/json' \
  -d '{"markdown":"# Hello Go","appearance":{"data-theme":"light"}}'

The first editor request receives a complete preview document. Later requests use "include_document": false and receive fragments. The iframe keeps its document, shared styles, and loaded libraries between edits. New features add their styles once; removed features remove their conditional styles. Chart instances are destroyed before replacement, and feature scripts initialize the new content.

The JSON response contains document, html, feature_head_html, body_end_html, and cached. Metrics include render_ms, input_bytes, html_bytes, and document_bytes. With include_document set to false, document is null and document_bytes is zero. Omit this option to retain the original full-document response. The Server-Timing response header also reports render time. document contains a complete HTML preview with links to this server’s assets. Keep the server available while you view the document.

Optional appearance keys are data-theme, data-palette, data-aesthetic, data-fontpack, and data-text-size. Values must occur in the bundled appearance catalogs. The API rejects unknown fields, malformed JSON, and invalid appearance choices with HTTP 400. It returns HTTP 413 for source above 200,000 UTF-8 bytes or a request above 1 MiB. Requests need application/json. Cross-origin render requests receive HTTP 403.

The handler runs one render at a time. Canceled requests leave the queue before rendering. An active render completes before the next render starts. The browser stops waiting after 30 seconds. The demo server has read and write timeouts.

This editor supports trusted local authoring. Authored HTML and styles remain available inside an opaque-origin iframe sandbox. Only renderer-generated scripts run during fragment updates. Reload the page to apply changes to authored scripts. Preview scripts cannot read the editor’s DOM or storage. Authored links and images can access external networks. Keep the default loopback binding for local use. Add authentication and suitable resource controls before remote deployment.

All built-in assets come from the server. Offline reload is not supported. For site builds and site-specific plugins, use the normal CLI.

Check persistent preview updates #

Start the Go workbench, then run its browser regression tests:

MARKATA_GO_WORKBENCH_URL=http://127.0.0.1:8767 \
MARKATA_TEST_CHROMIUM=/usr/bin/chromium \
uv run --with playwright python python/test_go_editor_browser.py -v

Set MARKATA_TEST_CHROMIUM to your Chromium executable. The tests check retained stylesheets, fragment responses, conditional styles, charts, and diagrams.

Benchmark the server #

The integration benchmark guide compares seven existing fixtures with the Python reference. It separates initial renders, uncached edits, and cached edits. Raw samples and reproduction commands are included.

Shared editor behavior #

Use the command palette to import or export a Markdown file. An oversized import leaves the current document intact. Search for New Post in the command palette to open a fuzzy picker for built-in starters and .md files in the site’s templates/ directory. Choose a starter to open its details form. The title and destination folder start with template defaults. The slug field stays empty when using the suggestion; its ghost text and the destination path update as the title changes. Enter a custom slug only when you want to override the title-derived filename. Creating the post opens the new file in the editor, where later edits autosave to the site. The footer reports whether the draft was saved. Storage failures leave editing and downloads available. See shared editor features and runtime differences for the comparison.

Command palette and Markdown commands #

To open the command palette with a complete example loaded, visit /?example.

Review changes before publishing (experimental) #

When editing a Markdown file inside a Git-backed workspace, select Publish in the upper-right header, search for Publishing: Review & Publish in the command palette, or press Ctrl/Cmd+S or Ctrl/Cmd+Shift+Enter. Vim mode also accepts :w; Emacs mode accepts Ctrl-X Ctrl-S. Each opens the same review dialog; none of them publishes immediately.

The dialog first waits until the exact text in the editor has been saved to the workspace. It then compares that saved source with the file from the last Git commit. Rendered diff opens first. Side by side shows both rendered versions and keeps matching sections in view while you scroll; mobile can switch between versions by tapping or swiping. Source diff shows unified Markdown, and Full diff opens the detailed source viewer. The Commit message tab shows the message for the local commit and lets you edit it. Metadata chips identify draft/published flag changes, slug changes, and conflicting publication flags.

The review can create a local Git commit for the selected page, using the message shown in the Commit message tab. After that commit, Push to origin is a separate action. Pushing does not prove that a deployment succeeded; when Builder Admin verification is configured, Check live status can confirm the deployed source revision. “Last committed” is not necessarily the live site revision. A scratch file must first be created or opened as a workspace Markdown post. If the workspace has no Git history, the review reports this rather than assuming a baseline.

The publish contract and planned deployment safety gates are defined in Editor publishing.

Verify a remote publication with Builder Admin (opt-in) #

Publishing has deliberately separate steps: review the exact Markdown and frontmatter, commit only that selected page, then explicitly push to origin. A successful push does not prove the site is live.

For a site deployed through Markata Builder Admin, the local editor can optionally verify the current release’s recorded source Git commit:

export MARKATA_PUBLISH_BUILDER_URL="https://builder.example.com"
export MARKATA_PUBLISH_BUILDER_TOKEN="<your authorized bearer token>"
markata editor --workspace ./site

Use an API token authorized for Builder Admin’s /api/v1/state. The editor stores neither the token nor builder URL in the browser; the local backend makes a short, authenticated, server-side GET request. Remote builder URLs must use HTTPS (loopback HTTP is permitted for development). Redirects are not followed, so bearer tokens cannot be forwarded to a different host.

After pushing, select Check live status. This checks revision.live_source_commit, with a fallback to the current release’s source revision when available. It reports Live · Verified only if that revision matches the exact pushed SHA. Unknown revision, unavailable API, unconfigured auth, failed build, and different live SHA never count as success.

This verification identifies the release’s source Git revision, not its byte-for-byte rendered output, CDN cache rollout, or availability at every public edge. Site URL health checks and other deployment providers need dedicated follow-up adapters.

Live Markdown editor with FastAPI

2026-10-28T00:00:00Z

Run the single-file example:

uv run examples/fastapi_editor.py

Open http://127.0.0.1:8765. Edit Markdown on the left. The preview updates after 250 milliseconds without edits. Narrow screens stack the editor and preview. The browser stores your draft locally. Use Download .md to save a file.

The example requires a Markata wheel containing the Python API from PR #1835. Until that API is released, install a wheel built from that PR:

uv run --with /absolute/path/to/markata-VERSION-PLATFORM.whl examples/fastapi_editor.py

Replace the wheel path with your local wheel. With Python and dependencies already installed, python examples/fastapi_editor.py also works. The server listens on localhost, port 8765. Press Ctrl+C to stop it.

Each preview uses an application-owned RendererPool through FastAPI. Two warm renderers start with the application’s lifespan and retain the workspace’s Markdown configuration. Inline assets support code highlighting, Mermaid, and Chart.js without separate asset routes. A fresh iframe document executes initialization scripts after each successful render. The iframe permits scripts and keeps the preview separate from the editor origin. Authored HTML and inline styles are enabled for this local authoring tool. The preview remains isolated from the editor origin.

The example limits input to 200,000 UTF-8 bytes and rendering to 15 seconds. Errors preserve the last successful preview. A crashed or timed-out renderer is replaced automatically; no new subprocess is started for ordinary requests. This example is a local development tool. It does not include accounts or shared storage.

Use the appearance button beside Download .md to open Markata’s full picker. Search color themes, switch light and dark modes, or select Style and Font tabs. Selections apply to the preview and persist across edits. Markata supplies the palette catalog, styles, scripts, and fonts. No site build runs during editing.

The footer shows Markata time, request time, input bytes, document bytes, and frame load time. Markata time includes queue wait, rendering, asset collection, and JSON parsing, but normally excludes process startup. Request time also includes HTTP transfer and browser JSON parsing. Frame load time measures iframe loading, not completed asynchronous diagrams. The 250-millisecond typing delay is separate from these measurements.

The preview uses the default site’s article wrappers, reading size, and spacing. It previews article content. It does not add site navigation, feeds, or post metadata.

Lucide shortcodes such as :lucide-globe: and :lucide/heart: display as inline icons in prose and headings. Markata bundles all 2,118 icons from Markata’s pinned Lucide pack, including its license. Code examples and unknown shortcodes stay unchanged.

The Markdown pane uses bundled CodeMirror with syntax highlighting, line numbers, line wrapping, and bracket matching. Select Keymap above the editor to use Default, Vim, Emacs, or Sublime bindings. Your choice persists in this browser. With Vim selected, press i to insert text and Escape to return to normal mode. Editor colors follow the appearance picker. CodeMirror requires no CDN requests.

Run the demo integration tests #

Use a virtual environment containing the built Markata wheel, FastAPI, Uvicorn, HTTPX, and Playwright. Run the endpoint checks against that installed wheel:

python -m unittest discover -s python/integration -v

Install Chromium and run the browser checks:

python -m playwright install chromium
python python/test_editor_browser.py -v

If Chromium is already installed, set MARKATA_TEST_CHROMIUM to its executable path. The tests reserve an available localhost port and stop their server afterward. They cover live edits, saved drafts, keymaps, initial appearance, picker changes, Lucide icons, responsive rails, and full-width desktop and mobile layouts. The wheel workflow runs both suites against the installed Linux wheel.

The first render returns the full preview document. Later requests set include_document to false, so the server returns only the rendered fragment, conditional styles, scripts, and metrics. The browser keeps its document and appearance styles loaded, then replaces the article content in the existing sandboxed frame. This avoids sending the large site CSS payload or reloading theme stylesheets after every edit.

See integration benchmarks for measured fixture timings and reproduction steps.

Shared editor behavior #

Insert Markdown commands #

Language assistance #

The Python and Go editors connect to Markata’s LSP through a same-origin WebSocket. The server selects the workspace with MARKATA_LSP_WORKSPACE; browser messages cannot change it. The endpoint accepts localhost and loopback IP hosts only. It is intended for local examples.

Both editors complete wiki links and Markdown document paths. They also complete command-catalog containers, their known attributes, and Mermaid diagram syntax. Press Ctrl+Space to request suggestions at the cursor. File-tree navigation is a separate feature.

To run the browser checks against both servers, build the Go binaries and set MARKATA_LSP_BINARY and MARKATA_WORKBENCH_BINARY as shown below:

go build -o /tmp/markata-editor-lsp ./cmd/markata-go
go build -o /tmp/markata-editor-workbench ./cmd/markata-workbench
MARKATA_LSP_BINARY=/tmp/markata-editor-lsp \
MARKATA_WORKBENCH_BINARY=/tmp/markata-editor-workbench \
python python/test_browser_lsp.py -v

Workspace files #

Set MARKATA_LSP_WORKSPACE to a cloned site before starting the server. The Files tree uses Markata glob and load plugins through the bundled Go binary. Select a file to edit a browser draft; download it to keep a copy. See workspace navigation.

Render Markdown in Python and FastAPI

2026-10-27T00:00:00Z

Install the official Go-based markata wheel containing this API (available with the release that includes this feature):

uv add markata fastapi uvicorn

Render a complete response with conditional CSS and JavaScript inlined:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from markata import render_async

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
async def index():
    result = await render_async("# Hello\n\n!!! note\n    Rendered by Markata.", inline_assets=True)
    return HTMLResponse(result.document(title="My app"))

render() offers the same options for synchronous applications. Both use the existing Go Markdown renderer shipped inside the Python wheel. Each call launches one process, so cache repeated content in your application. render_async() uses async subprocess I/O, terminates the process on timeout or cancellation, and does not block the ASGI event loop. timeout defaults to 30 seconds. Failures raise markata.RenderError.

Fragments and signals #

from markata import render

result = render("```go\nfmt.Println(42)\n```", inline_assets=True)
print(result.html)              # Article markup
print(result.features)          # code, admonitions, roads, mermaid, chartjs, ...
print(result.head_html)         # Ordered style tags
print(result.feature_head_html) # Only styles specific to this fragment
print(result.body_end_html)     # Ordered scripts

In an existing layout, insert head_html into the head, html inside an <article class="post-content">, and body_end_html after the article. These strings contain generated HTML; use the appropriate trusted-markup mechanism in your template engine. document(title="...", lang="en") creates that layout for you and escapes the title and language.

feature_head_html returns only conditional styles, without the shared variables, main, and component styles. The renderer returns core theme CSS plus only the optional assets the content requires. Mermaid and Chart.js use Markata’s vendored browser libraries; inline mode includes them too, without CDN requests. Inlining diagrams can make a response considerably larger. external_urls identifies any external browser dependencies; for the currently supported bundled features it is empty. Authored images and links still refer to their authored URLs.

Core theme CSS includes global styles. For an application with its own design, select the assets you want from result.assets and supply compatible CSS variables and .post-content styling. This API does not configure a site’s theme palette.

Serve assets separately #

The default inline_assets=False emits links under /markata-assets, or your asset_base. Each asset is a dictionary containing id, kind, placement, and content (or url for external assets). Asset IDs are suitable for caching and deduplication; scripts must keep their manifest order.

A small app can precompute its content and serve the bundled assets directly:

from fastapi import FastAPI, HTTPException
from fastapi.responses import HTMLResponse, Response
from markata import render

app = FastAPI()
page = render("# Example\n\n```python\nprint('hello')\n```", asset_base="/md-assets")
assets = {asset["id"]: asset for asset in page.assets if "content" in asset}

@app.get("/md-assets/{asset_id:path}")
def asset(asset_id: str):
    item = assets.get(asset_id)
    if item is None:
        raise HTTPException(status_code=404)
    media_type = "text/css" if item["kind"] == "style" else "text/javascript"
    return Response(item["content"], media_type=media_type)

@app.get("/", response_class=HTMLResponse)
def index():
    return page.document(title="Example")

For multiple pages, combine their bundled assets by ID and retain each page’s ordered generated initialization scripts. Generated chart IDs are local to one render result: render all Markdown for a document together. Do not deduplicate generated scripts across unrelated results. If browser content is replaced after page load, the application must execute its initialization scripts; simply assigning innerHTML does not execute them.

Scope and trusted content #

Supported: Markata’s Markdown extensions, syntax highlighting, containers, admonitions, Mermaid, Chart.js, roads, sortable tables, and opt-in checklists. Rendering does not run a site build; site-dependent link resolution, embeds, image transforms, and other lifecycle plugins are outside this API.

Raw authored HTML is disabled by default. Set unsafe=True only for trusted content. Rich Markdown output is not an HTML sanitizer; sanitize untrusted content using your application’s policy. Inline styles and scripts also require a compatible Content Security Policy. Applications with strict CSP should serve assets themselves and apply their own nonce/hash policy to initialization scripts.

CLI protocol #

The Python API uses the same machine-readable interface available to other languages:

printf '# Hello\n' | markata render --json --inline-assets

Without --json, markata render emits just the HTML fragment. --unsafe enables raw HTML; --asset-base /static/markdown changes linked bundled asset URLs. This command reads stdin without discovering a site configuration or writing files.

Reuse the site’s appearance controls #

Load the catalog once when the application starts:

from markata import appearance, render_async

presentation = appearance(asset_base="/markata-assets")
result = await render_async("# Hello", inline_assets=True)
html = result.document(appearance=presentation, palette="ayu-dark", mode="dark")

presentation.picker_html contains the site’s appearance controls. Insert presentation.controls_head_html in the host page’s head and presentation.body_end_html after its content. Serve presentation.assets through exact path lookup. controls_head_html omits site page-layout styles. Complete preview documents use head_html internally. Each asset value is bytes. Use CSS, JavaScript, or WOFF2 response types as appropriate. The asset base also applies to font URLs. No site build or filesystem writes occur.

The controls reuse the site’s palette, aesthetic, font, size, and loading catalogs. document() now uses site article wrappers. Set mode, palette, aesthetic, fontpack, and text_size to select appearance. Unknown catalog values raise ValueError. Lucide shortcodes render through Markata’s existing icon implementation.

For an isolated preview iframe, set appearance_bridge=True. The parent can send {type: "appearance", attributes: {...}} with data-theme, data-palette, data-aesthetic, data-fontpack, and data-text-size choices. The bridge accepts messages from its parent and validates values against the catalogs. Keep the iframe sandboxed with allow-scripts and without allow-same-origin.

For live edits, the parent can also send {"type": "markdown-render", "html": "...", "feature_head_html": "...", "body_end_html": "..."}. The bridge replaces .post-content, updates render-specific styles, loads new feature scripts once, runs generated scripts, and dispatches view-transition-complete. It does not replay DOMContentLoaded. The host can therefore keep shared preview stylesheets loaded between renders.

The single-file editor example contains CodeMirror and application behavior. Markata supplies its preview document, icons, appearance picker, and assets. Applications must explicitly enable unsafe=True to render authored HTML and style blocks.

Installation size and offline icons #

The renderer retains the full pinned lucide-static 1.48.0 catalog for offline icon shortcodes. This provides consistent icon availability without downloads or a configurable subset. The catalog contains 2,118 SVG files: 1,026,506 source bytes, or approximately 0.98 MiB. Compressing their concatenated bytes with gzip produces approximately 97 KiB. These asset measurements do not measure the catalog’s exact contribution to a compiled binary or wheel. A stripped Linux amd64 CLI built with Go 1.26.3 measured approximately 66 MiB before wheel compression. The complete CLI also contains themes, fonts, browser libraries, and build features. Wheel sizes vary by operating system and architecture.

Lucide’s ISC and derived Feather MIT notices remain embedded in the binary. Wheels also provide readable notices in markata-<version>.dist-info/licenses/lucide.txt.

An installed POSIX binary with its executable bit preserved can render from read-only site-packages. Rendering does not require permission changes in that installation. If another installer removes the executable bit, reinstall the official wheel with executable permissions. The permission-repair fallback needs permission to change the binary’s mode.

Each Python render call starts a subprocess. The measured benchmark post took approximately 137 ms through the Python API. For frequent live edits, use the persistent Go workbench instead of starting a subprocess for every request. See integration benchmarks for timing boundaries and reproduction commands.

Go module import path cutover

2026-10-27T00:00:00Z

The canonical Go source module for Markata (still on the 0.x line) is github.com/WaylonWalker/markata, following the October 18, 2026 GitHub repository swap. It is independent of the original Python module, which now lives at WaylonWalker/markata-py.

Existing users #

Using the CLI or builder containers: you can keep the markata-go binary alias, markata-go.toml, [markata-go], MARKATA_GO_* and legacy GHCR names for now. See the naming migration guide.
Importing Go packages: replace imports starting with github.com/WaylonWalker/markata-go/ with github.com/WaylonWalker/markata/, and run go mod tidy. The Go module’s own declaration has changed as well.
Pinned historical Go consumers: existing historical tags for github.com/WaylonWalker/markata-go have not been deleted. Avoid depending on both the historical and new module paths in the same dependency graph; they describe the same source with different module identities and may result in duplicate packages.
Python users: historical pinned Python releases remain available on PyPI, but current PyPI releases install the Go CLI after a version break. A Go CLI install must not silently overwrite an existing Python markata executable.

Canonical source install #

go install github.com/WaylonWalker/markata/cmd/markata@main

# Legacy Go executable remains available from the canonical module:
go install github.com/WaylonWalker/markata/cmd/markata-go@main

For reproducible installations, pin an already published, verified release tag rather than @main when that tag supports your command and module path. The name migration does not authorize any new release, prerelease or tag. Validate Go imports, installer compatibility, builder images, Argo CD sources and representative site builds independently while remaining on 0.x.

Change control #

The module path migration changed only tracked Go files, go.mod, and GoReleaser’s linker symbol package paths. The deterministic rewrite script lives at scripts/migrate-go-module-path.py; the dedicated PR workflow fails if any old module import remains.

These are not reasons to rename Kubernetes PVCs, releases, secrets, Helm chart names, historical Docker tags, old Go binaries, or Python PyPI distributions.

Accessible Chart.js figures and fallbacks

2026-10-26T00:00:00Z

chartjs fenced blocks render a standard HTML data table at build time. They retain a JavaScript-free representation even if the Chart.js CDN is unavailable, the reader disables JavaScript, or interactive rendering fails.

The theme adds a Chart.js canvas alongside an expanded Chart data disclosure. For charts using the options below, successful Chart.js initialization collapses the disclosure, which remains available for exact values or screen-reader users. If the library fails to load, the table keeps its configured state.

Example #

Chart data

Chart data
Label	Build seconds
Full	46
Incremental	21

The renderer emits semantic table headers and cells without a second chart library or a network request. For unusual configurations such as scatter charts with object-valued x/y entries, the original JSON remains available in a Chart configuration disclosure instead of fabricating tabular labels. Huge tables (more than 200 labels or 12 datasets) also fall back to the original configuration to bound generated HTML.

Chart data is treated as untrusted Markdown input: HTML labels are escaped and chart JSON is safely encoded before inclusion in an inline script.

Titles, captions, and compact figures #

Add plain-text title and/or caption keys at the top level of the chart JSON:

```chartjs
{
  "title": "Build time",
  "caption": "Seconds per build; lower is better.",
  "data_display": "collapsed",
  "type": "bar",
  "data": {
    "labels": ["Full", "Incremental"],
    "datasets": [{"label": "Seconds", "data": [46, 21]}]
  },
  "options": {"indexAxis": "y"}
}
```

The built-in theme renders a responsive surface card with a left-aligned, non-italic figcaption. Its title is not a heading, so it does not enter the TOC. The canvas is labelled by the title and references the figcaption. Short horizontal bar figures (up to four labels) use a compact canvas, capped at 130px; other figures retain normal Chart.js sizing. You do not need page CSS or JavaScript. Neither title nor caption interprets HTML or Markdown.

These authoring keys are stripped before Chart.js receives the JSON. We use JSON metadata rather than fence attributes because the Markdown renderer retains the language but not arbitrary fence-info options (the legacy CSV HTML matcher is not a reliable authoring path for this). Chart.js’s own chart title remains available separately under options.plugins.title.

Initial data disclosure state #

[markata-go.chartjs]
data_display = "open" # default; or "collapsed"

Set top-level "data_display": "open" or "data_display": "collapsed" in an individual chart to override the site default, with or without a figure. Collapsed details still have a visible, keyboard-operable summary without JS. Successful rendering of an opted-in chart collapses the disclosure regardless of its initial state; a loading/rendering error leaves that state intact. Invalid values produce a configuration error (site setting) or a visible chart error (per chart). With no new options, existing chart markup and the default-open fallback remain unchanged.

Legacy charts without these options also retain their original initialization script: it attempts to collapse the wrapper div rather than the disclosure, so their data stays open. Add a title, caption, or per-chart data_display (or set the site’s data_display to "collapsed") to opt into corrected behavior.

Behavior #

No-JavaScript: canvas is hidden; table or configuration is reachable in details (expanded by default).
JavaScript working: canvas becomes visible; opted-in charts collapse the data disclosure, which can always be reopened.
Chart.js loading or rendering error: canvas remains hidden; fallback remains reachable in its configured initial state.
Multiple charts per post: each chart has its own fallback.
Pages without chartjs blocks are unchanged.

This is an accessibility and progressive-enhancement improvement to the existing Chart.js plugin. It is not a new chart data format, SVG exporter, or automatic visual data verification.

Horizontal bar defaults #

A horizontal bar chart with one dataset and up to five labels uses thin, rounded bars and a compact aspect ratio by default. Set bar geometry such as barThickness or borderRadius in the dataset, options, options.datasets.bar, or options.elements.bar to use your own geometry. Set options.aspectRatio or options.maintainAspectRatio to control chart sizing. Charts with multiple datasets or more than five labels keep Chart.js defaults.

Dataset indexAxis overrides options.datasets.bar.indexAxis, which overrides options.indexAxis. Compact defaults apply only to the resulting horizontal orientation.

Default bars have a maximum thickness of 14 pixels. They shrink on narrow screens to prevent overlap.

URL mentions provider integration (initial foundation)

2026-10-22T00:00:00Z

The pkg/urlmentions package consumes version 1.0 of the public URL mentions protocol.

Provider indexes:

urlmentions.Client.Fetch(ctx, endpoint) retrieves all pages and returns a map from provider-supplied references[].normalized_url to source entries. It bounds response sizes and page counts, rejects non-HTTPS starting URLs, and disallows cross-origin pagination. The caller should use an HTTP client with redirects restricted to the same origin and enforce a build-time budget.

This is phase one only. The package is not registered as a build plugin, does not fetch either provider automatically, and does not render UI yet. Follow-up work: align canonical URL normalization with the provider protocol; cache provider pages/ETags; configure providers; map post canonical, external target, and reader URLs; SSR accessible favicon badges with no-JS fallbacks; graceful offline builds and snapshot tests.

Do not treat this PR as production feature-complete.

Markdown example preview and source

2026-10-21T00:00:00Z

A source disclosure can follow any rendered Markdown example. Markata renders this as native HTML <details>, so it supports mouse, keyboard, and screen readers without JavaScript. No new JS bundle is necessary.

The source is explicitly authored: this feature does not automatically duplicate Markdown, execute snippets, or copy untrusted HTML into the page.

Basic example #

::: md-layout

:::: md-card
### Preview

This is **bold** and this is `inline code`.

::::

:::: md-source {data-label="See how it is written"}

```markdown
### Preview

This is **bold** and this is `inline code`.
```

::::

:::

Use a longer backtick fence (four backticks or more) around an example containing nested triple-backtick code fences, as in other Markdown guides.

The label is optional and defaults to Show Markdown source. Any authored label is escaped before being inserted in the disclosure summary.

Output and compatibility #

Static semantic HTML only; no JavaScript is required to open the source.
Source code uses the existing fenced-code highlighter and copy controls when those optional enhancements are present.
Source text is explicitly duplicated by the author, not extracted automatically from the preview. This helps avoid hidden dynamically generated markup and makes it easy to inspect what a post actually teaches.
The source disclosure is marked data-markata-ui="source-preview" so the rich post-copy command can omit its UI and avoid duplication there.
Search indexes and ordinary feed readers may still include explicitly authored source content; use this for deliberate educational examples, not every sentence of an article.

Interactive Markdown checklists

2026-10-21T00:00:00Z

Ordinary GFM task lists in Markata remain static, disabled, readable checkboxes. To let a reader check off tasks, wrap one or more task lists with the md-checklist container:

::: md-checklist {data-id="deployment"}

- [x] Back up the configuration
- [ ] Run the build
- [ ] Verify the live site

:::

The built HTML remains ordinary semantic Markdown list items with disabled checkboxes. On pages containing an md-checklist, Markata conditionally loads a small JavaScript enhancer that enables just those checkboxes. There is no global checklist runtime or JavaScript requirement for ordinary task lists.

data-id is optional. Supply a stable and unique ID per list in a page to save progress in the browser’s local storage under that page’s pathname. Without data-id, the list is interactive in the current session but does not persist. If storage is unavailable, checking tasks still works and nothing is uploaded to a server.

The task labels and original check states remain in the published Markdown. Local progress does not rewrite the site, user account, feeds or shared copy. The browser’s native checkbox provides keyboard and screen-reader support; list text is attached to each checkbox as an accessible label.

Graceful fallbacks #

JavaScript disabled or blocked: boxes stay disabled and the list is readable.
JavaScript enabled: only md-checklist containers become interactive.
Partial-page navigation: newly loaded checklists initialize once.
Content changes: if the count of tasks changes, outdated saved state is ignored rather than applied to the wrong items.
Privacy: only a boolean completion array is stored locally; no task text is persisted and no network request is made.

Roads

2026-10-20T00:00:00Z

A road is a path that draws itself as the reader scrolls. Each milestone on the path is a link from your post. Use roads for roadmaps, release histories, onboarding paths, project timelines, or any sequence that readers walk through.

Roads are built in to the default theme. You need no template, config, or plugin. Write a Markdown container named road, and put a list of links inside it.

Quick start #

::: road

- [Install markata-go](/docs/getting-started/) Step one
- [Configure your site](/docs/guides/configuration/) Step two
- [Pick a theme](/docs/guides/themes/) Step three
- [Publish feeds](/docs/guides/feeds/) Step four
:::

That renders as:

Install markata-go Step one
Configure your site Step two
Pick a theme Step three
Publish feeds Step four

Each list item is one milestone:

The link is the milestone title, and clicking it opens the page.
The text after the link is a small label, such as a date or step number. It is also shown in the hover card.

Wikilinks work too. A milestone written as [[my-post]] uses that post’s title, and its hover card shows the post’s description.

Set fixed progress #

Use fixed progress for a roadmap whose completion does not depend on scrolling. The normal scroll-driven progress remains the default.

::: road timeline {data-road-progress-mode="static" data-road-progress="65"}
- [Design](/design/)
- [Build](/build/)
- [Release](/release/)
:::

::: road steps {data-road-progress-mode="milestones" data-road-current="2"}
- [Design](/design/)
- [Build](/build/)
- [Test](/test/)
- [Release](/release/)
:::

static accepts a percentage from 0 to 100, with or without a % suffix. milestones accepts the number of completed entries. Values are clamped to the road’s range. Invalid values fall back to scroll progress. Fixed progress stays the same after scroll, resize, and view transitions. The original links remain available if JavaScript does not run. At 0, no entries are active. At 100%, or when all milestones are complete, all entries are active.

Choose a style #

Put the style name after road. The default style is winding.

Style	Good for
`winding`	Journeys, reading paths, story arcs
`timeline`	Dated events, changelogs, history
`steps`	Short processes of three to six steps
`snake`	Long ordered sequences, such as courses or series
`cycle`	Processes that repeat, such as sprints or seasons
`constellation`	Loosely related ideas or a “see also” map
`git`	Branching work, such as release trains or experiments
`editorial`	Timelines where each entry has paragraphs, lists, or images

Timeline #

::: road timeline

- [Project announced](/blog/announcement/) Jan 2026
- [Public beta](/blog/beta/) Apr 2026
- [Version 1.0](/blog/v1/) Jul 2026
- [Plugin marketplace](/blog/plugins/) Oct 2026
:::

Steps #

Steps read from left to right. On narrow screens they change to a timeline.

::: road steps

- [Draft](/handbook/draft/) write
- [Review](/handbook/review/) edit
- [Publish](/handbook/publish/) ship
- [Share](/handbook/share/) promote
:::

Install setup
Configure config
Theme style
Deploy ship

Snake #

The snake style wraps a long list back and forth across rows, like a board game.

::: road snake

- [Variables](/course/variables/) 1
- [Functions](/course/functions/) 2
- [Loops](/course/loops/) 3
- [Structs](/course/structs/) 4
- [Interfaces](/course/interfaces/) 5
- [Errors](/course/errors/) 6
- [Testing](/course/testing/) 7
- [Concurrency](/course/concurrency/) 8
:::

Cycle #

::: road cycle

- [Plan](/process/plan/) week 1
- [Build](/process/build/) week 2
- [Review](/process/review/) week 3
- [Retro](/process/retro/) week 4
:::

Write draft
Build preview
Review check
Publish ship

Constellation #

The points sit in fixed, scattered positions joined by fine lines. The layout is the same on every visit.

::: road constellation

- [[on-writing-clearly]] essay
- [[notes-on-focus]] note
- [[a-reading-list]] list
- [[why-plain-text]] essay
:::

Git #

The git style draws a commit graph with branches and merges. List the commits in order, and write the branch after each link:

After the link	Meaning
`main`	A commit on `main`. A new branch name starts a branch from the first branch (the trunk).
`fix/typo from feat/search`	Starts `fix/typo` from the latest commit on `feat/search`.
`main <- feat/search`	Merges `feat/search` into `main`. You can also write `←`.

::: road git

- [Initial commit](/changelog/#init) main
- [Add search index](/changelog/#search) feat/search
- [Update README](/changelog/#readme) main
- [Search results page](/changelog/#results) feat/search
- [Dark mode](/changelog/#dark) feat/dark-mode
- [Merge search](/changelog/#merge-search) main <- feat/search
- [Try a new palette](/changelog/#palette) spike/palette from feat/dark-mode
- [Dark mode polish](/changelog/#polish) feat/dark-mode
- [Keep the palette](/changelog/#keep) feat/dark-mode <- spike/palette
- [Release 1.0](/changelog/#v1) main <- feat/dark-mode
:::

The first commit’s branch is the trunk. Each branch gets its own lane and color. A merged branch frees its lane for the next branch.

Editorial #

Use the editorial style when each entry needs more than a title. Write a heading for each entry, then any Markdown under it: paragraphs, lists, checklists, quotes, images, or code.

::: road editorial

### [Discovery](/projects/redesign/discovery/) March

We interviewed twelve readers and found three common problems.

- [x] interviews
- [x] survey
- [ ] analytics review

### [Prototype](/projects/redesign/prototype/) May

> Smaller pages, bigger type, fewer clicks.

### [Launch](/projects/redesign/launch/) August
:::

Markdown Write #

Write posts in Markdown with frontmatter.

headings and lists
admonitions and containers
wikilinks

Templates Shape #

Change the layout with templates, or keep the defaults.

Deployment Ship #

Build static HTML and host it anywhere.

How editorial entries work:

The text after the heading link (March) becomes a small label above the title.
The rail fills in as the reader moves through the entries.
The headings stay real headings, so they keep their anchor links and appear in the table of contents. Use a heading level below your section heading, so the table of contents stays tidy. For example, use ### entries under a ## section.
A road whose first item is a heading uses the editorial style automatically, even when you write ::: road or ::: road timeline.

Editorial stories, icons, and reveal #

::: road editorial story reveal

### :lucide-key-round: RSA migration and faster job views
*2026 Q3*

A lead paragraph explaining what changed and why it matters.

- Faster job views
- Simpler key rotation
- Clearer audit trails
- Fewer manual steps

### A quieter milestone without an icon
*2026 Q4*

The ordinary rail dot still works.
:::

A leading :lucide-name: icon becomes a badge on the rail, muted until the entry is active. An emphasis-only paragraph immediately after a heading becomes the eyebrow above its title. Both work on all editorial roads, without story. If the heading already has a beside-link label, it takes precedence and the emphasis paragraph stays in the body. Mixed-content paragraphs are not labels.

Add story for larger balanced titles, a larger opening paragraph, generous spacing, and a prose measure of about 64 characters. Direct unordered lists without task checkboxes become diamond-bullet highlights with a top rule. Lists of four or more items use two columns at viewport widths of 1100px or more. Cards, stats, and figures can use the wider entry body. Without story, existing editorial typography stays unchanged.

Add reveal independently for scroll-triggered entry fades and gentle upward motion. It works with or without story, respects reduced motion, and does not animate print, anchor targets, or keyboard-focused entries. Entries stay readable without JavaScript or IntersectionObserver, even if the enhancement fails: reveal animates arriving content rather than hiding it until a callback runs.

More than one road #

A post can have any number of roads, in any mix of styles. Each road draws on its own as it scrolls into view.

Options #

Use the container attribute block for options:

::: road {data-road="timeline" data-road-spacing="80"}

- [Alpha](/releases/alpha/) v0.1
- [Beta](/releases/beta/) v0.5
:::

Option	Description
`data-road="STYLE"`	Selects the style. This is the same as `::: road STYLE`.
`data-road-spacing="N"`	Sets the vertical space for each milestone, in pixels.

To change the colors, set CSS custom properties in your site CSS:

.road {
  --road-accent: #3fb68b;  /* progress line, active dots, labels */
  --road-muted: #4a4f5a;   /* the path before it is drawn */
}

The defaults come from your palette’s --color-primary and --color-border-strong.

Using HTML instead of a container #

A raw HTML <div> also works. Leave a blank line after the opening tag and before the closing tag, so the list inside is parsed as Markdown:

<div class="road" data-road="timeline">

- [Kickoff](/notes/kickoff/) Jan 2026
- [Launch](/notes/launch/) Jun 2026

</div>

Accessibility and fallbacks #

Without JavaScript, a road shows as the ordinary list or headings that you wrote.
While a road loads, its space is reserved, so the raw list does not flash and the page does not jump. If the script fails, the list shows after 2.5 seconds.
Every milestone stays a real link that works with the keyboard.
When the reader asks for reduced motion, roads appear fully drawn, with no animation.
Roads keep working when readers move between pages with view transitions.

How roads load #

The road CSS and JavaScript load only on pages that contain a road. markata-go finds roads when it renders the post. CSS purge keeps the road styles in production builds, with no extra configuration.

Troubleshooting #

The road shows as a plain list. Check that the container closes with a line that contains only colons (:::). For a raw <div>, check for the blank lines around the list. After you change shared CSS or templates, do a clean rebuild.

Some list items are missing. Only list items that contain a link become milestones.

The git graph joins the wrong branches. Branch names must match exactly. A merge (main <- feat/x) must come after at least one commit on both branches.

Releasing Markata and rolling out every site

2026-10-20T00:00:00Z

Historical release documentation: These instructions describe the PyPI handoff before it occurred. Current PyPI releases install the Go CLI after the version break; older pinned releases are the Python implementation. See installation.

Release and deployment runbook #

A release is complete only when the tested tag, published artifacts, pinned workloads, completed content builds, and live sites agree. Creating a GitHub Release or updating a container tag is not enough.

1. Freeze a tested source revision #

Choose the exact main-branch commit after CI passes; record the 40-character SHA and release version. Maintain Go on 0.x; the next intended version after v0.13.0 is v0.14.0, not 1.0.
Require green lint, Linux core/CLI/site integration shards, macOS and Windows tests, and the snapshot package check. No unresolved red CI jobs.
In particular, TestCacheDeterminism_ColdVsHot_WithFeedsAllFormats must not depend on whether a public CDN happened to answer. If the test fails due to an intermittent download, investigate and rerun; record the diagnosis and a durable fix rather than treating a red run as pass.
Check any open release-affecting PRs and verify the approved source contains the intended code and docs.
Do not tag a moving main branch by accident: record the exact commit and compare it to the final release ref.

Local maintainer commands (Go 1.27 required):

git fetch origin --tags
git checkout main
git pull --ff-only
go test -race ./...
go vet ./...
goreleaser check
go run ./scripts/rendering-contract --check
# See the dedicated snapshot workflow and check-rc-artifacts.sh.
git rev-parse HEAD

After all checks pass, an authorized maintainer creates and pushes an annotated version tag:

git tag -a v0.14.0 <verified-full-commit-sha> -m "Markata v0.14.0"
git push origin v0.14.0

Do not push that tag while the release CI is red. This repository’s tag-driven Release workflow tests the tagged Go source, uses GoReleaser, and publishes signed binaries/checksums and SBOMs. The Docker workflow publishes tagged GHCR images including compatibility aliases.

2. Verify artifacts and document the release #

Check the canonical GitHub Release, specifically that it is not draft or failed and points to the expected commit.
Confirm markata_0.14.0_* and markata-go_0.14.0_* archives for Linux, macOS and Windows, checksums, Cosign signatures and SBOMs. Validate one installed binary of each name.
Confirm ghcr.io/waylonwalker/markata-builder:0.14.0 and its markata-go-builder:0.14.0 compatibility alias, as well as applicable search image sources. Do not infer publication solely from a workflow that was queued.
Include a curated summary, important compatibility notes, upgrade/rollback instructions and a link to v0.14.0 release notes in the published GitHub release body; the autogenerated commit changelog is supplemental.
Never replace a published tag with a different commit. Issue a subsequent patch release for corrections.

3. Publish PyPI independently, if its handoff gate is ready #

The current PyPI project name markata historically belongs to Python Markata. Publishing Go wheels is an intentional breaking installation-path handoff with its own review gate. See PyPI binary wheels.

Verify PyPI trusted publisher for owner WaylonWalker, repo markata, workflow pypi-go-wheels.yml and environment pypi.
Verify protected GitHub pypi environment and freeze/disable the old Python repository’s publishing workflow.
Run Go Markata PyPI wheels on main with version 0.14.0, publish=true and the workflow’s required confirmation only after the above prerequisites are satisfied.
Confirm all eight native wheel files on PyPI and test a new virtual environment with python -m pip install --only-binary=:all: markata==0.14.0, markata version and python -m markata version. Unsupported platforms may otherwise fall back to an older Python package.
Keep GitHub Release and PyPI states separately labelled until both have succeeded.

4. Deploy one immutable release through Argo CD #

Never change production GitOps to reference an unbuilt tag or a mutable latest image. In each multi-source Helm Application pin the chart targetRevision: v0.14.0 and align every Markata fetch, builder and search image tag: "0.14.0" with that source. Preserve other application settings, storage modes, secrets and feature flags. If search is intentionally independently pinned, verify the compatible search version first; record the exception explicitly.

Use a separate GitOps PR that can be held until all artifacts are verified. Progressive rollout:

Order	Surface	GitOps source	Expected action
1	`go.waylonwalker.com`	`argo-apps/apps/go-waylonwalker-com.yaml`	Canary chart/builder/search pins; rebuild and smoke
2	`waylonwalker.com`	`argo-apps/apps/waylonwalker-com-prod.yaml`	Full site build; smoke archive/images/sidebar/navigation
3	`rhiannonwalker.com`	`argo-apps/apps/rhiannonwalker-com-prod.yaml`	Build via Builder Admin and confirm site
4	`wyattbubbylee.com`	`argo-apps/apps/wyattbubbylee-com-prod.yaml`	Build via Builder Admin and confirm site
5	`recipes.waylonwalker.com`	`k8s/recipes-waylonwalker-com/deployment.yaml` and `site-config.yaml`	Replace both mutable `latest` references with `0.14.0`; confirm recipe build

The markata-docs Deployment uses a separate Python-based documentation generator and separately versioned docs images; it is not a Markata CLI runtime and should not be falsely counted as an old Markata deployment. platgo currently has an example/commented Markata builder setting, not an active runtime. A historical rhiannonwalker source-seed bootstrap Job has a pinned image; audit it only if bootstrap is still required.

For each Argo Application: compare desired manifests with running pod image digests and chart revision; confirm it synced successfully and is healthy. On Builder Admin, compare running binary revision with most recent successfully published build. If the feature’s automatic build-on-new-revision does not run, invoke a full build through the authenticated builder. Verify site content before counting it complete.

Example read-only checks (use your configured kubectl context; do not assume remote cluster access from CI):

kubectl -n argocd get applications
kubectl -n waylonwalker-com-prod-notes get deployments,pods
kubectl -n go-waylonwalker-com-notes get deployments,pods
kubectl -n rhiannonwalker-com-prod-notes get deployments,pods
kubectl -n wyattbubbylee-com-prod-notes get deployments,pods
kubectl -n recipes-waylonwalker-com get deployments,pods
curl -fIsS https://waylonwalker.com/
curl -fIsS https://waylonwalker.com/archive/
curl -fIsS https://waylonwalker.com/images/

5. Rollback and closeout #

Before each promotion, record old chart SHA, old image digests, the most recent good site release identifier and an application-specific rollback procedure. If the new build fails, pause further promotions, restore the old immutable chart/image pins in GitOps, reconcile, and activate the last known-good site release. A content rollback and a binary rollback are different operations; verify both.

Keep a deployment record with: release version, tag commit, binary artifacts, PyPI status, container digests, Argo commit, per-site desired/running image, build revision, site release ID, full-build result, public smoke results and timestamp. Mark each site verified, blocked, or not applicable; never call the release “deployed everywhere” with unknowns.

Status badges, metrics, gauges, and sparklines

2026-10-20T00:00:00Z

Status, metrics, gauges, and sparklines #

Markata’s Markdown containers can render compact, theme-aware operational summaries without using JavaScript. Combine these components with the responsive layout primitives to produce the same kind of dashboard-like reporting found in modern chat interfaces.

The components are presentation, not automatic monitoring. Authors supply the measurements; Markata does not calculate or verify them.

Components #

Container	Role
`md-status`	Compact inline status with an optional semantic tone
`md-stat`	First paragraph is label; second is large value; third is optional secondary label
`md-delta`	Side-by-side comparison caption and emphasized result
`md-meter`	Native HTML `<meter>` for measurements like free disk space
`md-progress`	Native HTML `<progress>` for partially completed tasks
`md-sparkline`	Static inline SVG trend line from a short series of numbers

data-tone="success", data-tone="caution", and data-tone="danger" use the site’s existing semantic palette colors. Unknown tones use the ordinary theme accent. Both gauges require finite numbers data-value and data-max where max is positive and 0 ≤ value ≤ max. They also require a descriptive data-label, which becomes the accessible label on the native HTML element.

When an attribute is missing or invalid, the container still renders its Markdown body normally and no graphical gauge is added. The text should always include the exact value so the page is understandable in text-only readers and feeds.

Verified result badge #

::: md-status {data-tone="success"}

NVMe cleanup verified

:::

Do not use green color alone to communicate success: include the literal status wording, as above.

Before/after metrics and native meters #

::: md-layout

Falcon3 NVMe — before and after cleanup

:::: md-columns

::::: md-stat {data-tone="caution"}
Before

**83 GiB**

18% free

:::::: md-meter {data-value="18" data-max="100" data-label="Before cleanup: 18 percent free" data-tone="caution"}

::::::

:::::

::::: md-stat {data-tone="success"}
After

**212 GiB**

45% free

:::::: md-meter {data-value="45" data-max="100" data-label="After cleanup: 45 percent free" data-tone="success"}

::::::

:::::

::::

:::: md-delta {data-tone="success"}
Space recovered

**+129 GiB**

::::

:::

These remain normal Markdown paragraphs and nested containers. Use longer colon fences for deeper nesting, and place blank lines before bare closers.

Trend sparklines #

A sparkline shows the shape of a series next to the number it explains. Give data-values as two or more finite numbers, separated by spaces or commas, and a descriptive data-label. The line is drawn at build time as an inline SVG, so it needs no JavaScript. The Markdown body stays as a visible caption.

::: md-stat {data-tone="success"}
Jobs run

**222,421**

Year 4 ran 3x the jobs of year 3

:::: md-sparkline {data-values="8120 21400 48300 144601" data-label="Jobs per year, years 1 to 4" data-tone="success"}

Years 1–4

::::

:::

The sparkline draws only a line by default. Add the area modifier class to shade the area under the line:

::: md-sparkline area {data-values="12 18 15 31 44" data-label="Jobs per week"}

Last five weeks

:::

The line fills the container width and scales between the lowest and highest values. It does not start at zero, so it shows shape, not size. Put the exact numbers in the text or a table when the reader needs them. The SVG’s accessible name gives the label, point count, first and last values, low, and high.

A sparkline accepts up to 500 points. With fewer than two points, a missing label, or a value that is not a finite number, no line is drawn and the caption renders as normal.

A build progress bar #

A task-completion indicator is not the same as a measured storage percentage. Use md-progress only when a process is underway.

::: md-progress {data-value="7" data-max="10" data-label="Build steps completed"}

7 of 10 build steps finished.

:::

Full report with a normal Markdown table #

Use the example page for the complete composition, including the existing semantic GFM table. Future sortable table behavior will work independently of these static metrics and should never be needed to see the content.

Compatibility and accessibility #

Fully rendered at build time; no component JavaScript or network requests.
The source Markdown body and numeric labels remain readable in plain text.
Native meter and progress provide standard accessible semantics.
Sparklines are role="img" SVGs with a generated accessible summary.
Color tones inherit from the active theme, including alternate palettes.
Nested grids stack at mobile widths using the layout primitives.