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.

Triage a Markata problem with a coding agent

2026-10-19T00:00:00Z

Troubleshooting with `markata triage` #

When your Markata site behaves unexpectedly, start with:

markata triage

Markata collects lightweight local diagnostics, then displays a fuzzy picker with the coding agents it finds on your PATH. It also offers Copy to clipboard and Print to stdout. Pick a coding agent and the agent opens with a troubleshooting prompt: it should ask you what happened first, instead of making guesses or immediately modifying your site.

The command works with the new markata binary and the backwards-compatible markata-go binary.

Where the prompt goes #

Option	Behavior
`markata triage`	Fuzzy picker in an interactive terminal; prompt-only stdout when piped or redirected
`markata triage --to opencode`	Start an interactive OpenCode session with an initial prompt
`markata triage --to claude`	Start an interactive Claude Code session with an initial prompt
`markata triage --to codex`	Start interactive Codex with an initial prompt
`markata triage --to gemini`	Start interactive Gemini CLI
`markata triage --to cursor`	Start interactive Cursor Agent
`markata triage --to clipboard`	Copy the prompt using the platform’s clipboard helper
`markata triage --to stdout`	Print only the Markdown prompt (ideal for pipes)
`markata triage --agent codex`	Alias for selecting a specific installed agent
`markata triage --issue "Images are missing"`	Include a short first-hand problem description

Harness detection only checks that an executable is on PATH. It does not guarantee the agent is authenticated or configured with a model. Unsupported or missing agent names produce an error; clipboard and stdout still work.

For Linux clipboard handoffs, install wl-copy, xclip, or xsel. macOS uses pbcopy; Windows uses clip.exe. A missing helper is reported as an error; use stdout instead.

Piping to an agent #

--to stdout is clean Markdown with no banner, terminal formatting, or interactive picker. It can be redirected to a file or piped directly into another CLI:

# Interactive picker disabled automatically in a pipe
markata triage --to stdout | codex exec -

# Use OpenCode's noninteractive prompt runner
markata triage --to stdout | opencode run

# Use Claude Code's print mode
markata triage --to stdout | claude -p

# Save and inspect the context before sharing it
markata triage --to stdout > triage-prompt.md

Piped agent commands may be noninteractive. If you want the agent to ask questions back-and-forth in a terminal, use --to opencode, --to claude, etc., or select an agent from the fuzzy picker.

With --no-input, or if stdin or stdout is not a terminal, the default --to auto prints to stdout; it never unexpectedly launches an agent. Explicit interactive agent launch requires a terminal. Press Escape to cancel the fuzzy picker without launching anything. Closing a pipe early (for example, markata triage | head) exits quietly. The primary prompt remains plain and pipeable with --no-color, NO_COLOR, and --quiet.

Triage remains available even when a requested --site-dir or MARKATA_GO_SITE_DIR directory is missing or inaccessible; it records that problem in its diagnostics instead of failing before collecting context. Config file contents are never parsed as part of triage.

What is collected #

The prompt describes:

The running triage CLI’s embedded version, commit, and build date
Operating system, architecture, Go runtime, and (on Linux) OS distribution
Location of the Markata executable and an inferred, not guaranteed, installation method
Working/site directory and names of local Markata config files (or explicit config path)
Presence of a small allowlist of environment variables, not their values
Links to Markata’s source, documentation, and issue tracker

It does not read your configuration contents, logs, passwords, authentication tokens, arbitrary environment values, or other user files. Home-directory prefixes in paths are abbreviated when possible. Because paths may still be personal, inspect the prompt before sharing it publicly or sending it to a new provider.

A key distinction: the Markata version used to generate the prompt may be different from the version that failed in production, Docker, CI, or a remote builder. The agent is instructed to ask which version and execution environment actually experienced the problem.

What the agent should do #

The prompt asks the agent to first understand your symptoms, intended behavior, reproduction steps, and exact errors. It should check whether the issue is with site content, configuration, templates, a plugin, installation, or Markata itself; investigate read-only first; and ask permission before changing files, running mutating commands, or publishing an upstream issue.

If you already have a clear problem statement, add --issue and the agent should not make you repeat it.

For common manual troubleshooting, see the Troubleshooting guide and the CLI reference. The source repository and issue tracker are available when a fix belongs upstream.

Quickstart

2026-10-18T00:00:00Z

Already installed? This is the shortest path from an empty directory to a local website.

If not, start with Installation.

1. Create your site #

mkdir my-site && cd my-site
markata config init
markata new "Hello World"

config init creates markata-go.toml. That’s the correct filename for the Go project today, despite the new command name.

2. Preview it #

markata serve

Open http://localhost:8000. The development server watches for changes and rebuilds your site as you edit.

3. Teach your agent #

markata agent list-agents
markata agent install
markata agent doctor

The default project install detects a supported agent or uses .agents/skills/markata-go-site/. For a specific harness:

markata agent install --agent opencode
# or: markata agent install --agent claude-code

See the agent guide for Codex, Cursor, Claude Code, OpenCode, and global installs.

4. Write #

Open pages/post/hello-world.md. Edit the Markdown below its YAML frontmatter and save. Your browser should update.

Prefer a draft while working? Run:

markata new "My draft" --draft

See Authoring for a complete walk-through.

5. Build for production #

markata build

The output is in output/ by default. Deploy that generated folder to any static host. Start with the deployment guide.

Need help? #

markata --help
markata config validate
markata agent doctor
Troubleshooting

Install Markata

2026-10-18T00:00:00Z

The preferred executable is markata. The installer also installs the compatibility command markata-go.

Markata is a single Go binary; you do not need Python to run it. Choose your installation method.

Curl (Linux / macOS) #

Read the installer source before running it, especially on managed machines.

curl -fsSL https://raw.githubusercontent.com/WaylonWalker/markata/main/install.sh | bash
markata version

This checks GitHub Releases, detects platform and architecture, and installs into a writable binary directory (usually ~/.local/bin for non-root users). Add that directory to your PATH if necessary.

Bash (download then inspect) #

curl -fsSLo install-markata.sh https://raw.githubusercontent.com/WaylonWalker/markata/main/install.sh
less install-markata.sh
bash install-markata.sh
markata version

To choose an install location or a version, pass variables to the Bash process:

MARKATA_INSTALL_DIR="$HOME/.local/bin" MARKATA_VERSION="v0.13.0" bash install-markata.sh

The script refuses to overwrite an unrelated markata executable, including one belonging to Python Markata.

mise #

Install from GitHub Releases:

mise use -g github:WaylonWalker/markata
markata version

Or omit -g to pin it in your project’s mise configuration. Check the installed command name: historical release archives may still contain markata-go rather than markata.

GitHub download #

Get the archive for your operating system and architecture from GitHub Releases. Verify its checksum against the accompanying checksums.txt, extract it, and put the executable on your PATH.

Historical v0.13.0 release archives are named markata-go_<version>_<os>_<arch>.tar.gz (Windows uses .zip). New releases may use markata_.... Do not guess archive filenames: select one from the actual release assets.

Go (source build) #

Use Go 1.27 or newer for the current source module:

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

Until a release tag contains the new entry point, use @main for this canonical command rather than @latest. Make sure $(go env GOPATH)/bin is in PATH.

PyPI (uv, uvx, pip, pipx) #

The current markata PyPI distribution installs the Go CLI following the version break from the original Python implementation. Existing Python-era versions remain available when explicitly pinned; the Python source lives in markata-py. This is a CLI transition, not Python API compatibility.

uv tool install markata
uvx markata --help
pip install markata
pipx install markata

Use one installation method. On platforms without a matching Go binary wheel, check the selected package version and executable rather than assuming a compatible wheel is available.

Verify and start #

markata version
markata --help
mkdir my-site && cd my-site
markata config init
markata new "Hello World"
markata serve

Continue with the quickstart. If you already use markata-go, that command remains supported. Keep your markata-go.toml filename and [markata-go] configuration section; the Go config file has not been renamed. See Naming migration.

For more options, check troubleshooting and the release list.

Troubleshooting with an agent #

Run markata triage to gather a bounded diagnostic prompt and choose a detected coding agent, clipboard, or stdout. See the triage guide.

Markata documentation

2026-10-18T00:00:00Z

A fast static site generator for people and their agents.

Let’s be honest. We’re all running agents these days. They manage everything.

Write Markdown. Give your agent the right context. Publish a site you own.

Start here #

Install Markata using curl, a shell, mise, GitHub Releases, or Go.
Quickstart — create your first site and preview it locally.
Set up your agent — install the bundled markata-go-site skill.
Write your first post — Markdown, frontmatter, drafts, images, and links.
Publish — deploy the generated static files.

Explore as you grow #

Releases #

v0.14.0 release notes — what’s new, compatibility and upgrade guidance (release preparation)
Release and deployment runbook — tag, artifacts, GitOps rollout, build verification and rollback

Markata is still 0.x. The older markata-go command remains compatible. New Go sites should continue to use markata-go.toml and [markata-go] until the configuration migration is complete.

PyPI version break: Current markata releases install the Go CLI; older pinned releases remain the original Python implementation. See installation for details.

If something fails, run markata triage or see the triage guide.

Use Markata in a web application: Python and FastAPI rendering, the Go workbench, or the browser WASM workbench. See renderer integration benchmarks for measured timings.

Markata GitHub repository cutover — owner runbook

2026-10-18T00:00:00Z

Historical runbook: The GitHub repository swap was completed on October 18, 2026. Do not rerun the rename command. Go is at WaylonWalker/markata and Python at WaylonWalker/markata-py; the Go project remains on 0.x without a release tag planned by this migration.

No release tag, PyPI overwrite, or production deployment is implied by a repository rename. Source-path, package and deployment migrations are separate gates.

Identity and sequencing #

GitHub repository	Before	After	Stable repository ID
Historical Python	`WaylonWalker/markata`	`WaylonWalker/markata-py`	`333449359`
New Go implementation	`WaylonWalker/markata-go`	`WaylonWalker/markata`	`1140034778`

Order is mandatory. The Python repository must vacate markata before the Go repository can claim it. When Go takes over WaylonWalker/markata, existing Python links to that name will start opening the Go repository, not Python. Do not rely on GitHub redirects to keep Python bookmarks pointing to Python.

The GitHub connector currently does not expose repository rename permissions. An owner can use repository Settings → General → Repository name, or the guarded script below with an authenticated gh CLI that has repository administration permissions.

Before moving either repository #

Confirm Python PR #175 (identity notice) and #176 (disable automatic PyPI publishing, stabilize Python source URLs) are merged.
Confirm Go #1629 (dual CLI), #1671 (canonical/legacy config environment aliases), #1672 (legacy/canonical GHCR images), and #1673 (GoReleaser release target) are merged.
Verify GitHub Actions, branch rulesets, collaborators, Cloudflare Pages integrations, GitHub Apps and registry publication rights for both repos. Confirm the current Go production builder image is still retrievable.
Do not publish another Python package to PyPI as an incidental result of a code/metadata edit. PyPI markata is still the historic Python package. markata-py is not automatically a new PyPI distribution.
Do not change site configs called markata-go.toml, old Go module paths, sealed secrets, existing PVC names, Kubernetes Service identities, or Helm release names simply to match branding.

Run from a clone of the Go repository:

gh auth status
bash scripts/markata-repo-cutover.sh preflight

The script checks immutable GitHub repository IDs, merged preparation PRs and that markata-py is unoccupied. It refuses ambiguous API/auth failures.

Perform the owner-level rename #

Use GitHub Settings manually in the exact order above, or run:

bash scripts/markata-repo-cutover.sh apply --execute

This requires an interactive explicit confirmation and checks repository IDs both before and after each rename. There is no automatic rollback. If the first rename succeeds and the second fails, stop and diagnose the second failure; Python will already be at markata-py.

Once done, re-clone the Go repository or update its checkout:

git remote set-url origin https://github.com/WaylonWalker/markata.git
git remote -v
bash scripts/markata-repo-cutover.sh postcheck

For Python checkouts, point origin to https://github.com/WaylonWalker/markata-py.git.

Post-swap compatibility work — while remaining on 0.x #

Go source/module: migrate go.mod, import paths, generated code, build/linker flags, GoReleaser import targets, CI, embedded paths, and code generators to github.com/WaylonWalker/markata together. Test go test ./..., representative external Go consumers, cross-platform installs and go mod tidy. Never silently rewrite historical Python markata.toml configuration or convert its semantics to Go.
Installer/docs: update canonical install scripts, release links, README badges, bundled agent skill and documentation to the new Go repository. Keep both markata and markata-go executables and old release archives. A raw.githubusercontent.com URL pointing at an old repository path must not be assumed to redirect after the move.
Images/Argo: verify the Docker job pushes identical tagged content to ghcr.io/waylonwalker/markata, ghcr.io/waylonwalker/markata-go, ghcr.io/waylonwalker/markata-builder, and ghcr.io/waylonwalker/markata-go-builder after the repo rename. Confirm GHCR Actions permissions to create/push the new package names. Pin images by digest when practical; do not delete old image tags.
Home infrastructure: audit WaylonWalker/homelab-argo Argo sources and their repo access credentials, especially:
- argo-apps/apps/waylonwalker-com-prod.yaml (currently pinned to a commit)
- argo-apps/apps/go-waylonwalker-com.yaml
- argo-apps/apps/wyattbubbylee-com-prod.yaml
- argo-apps/apps/rhiannonwalker-com-prod.yaml
Their Git repository URLs were updated by homelab-argo#111. Verify actual Argo CD repository access and application health rather than treating a PR merge as successful production reconciliation. Also audit k8s/recipes-waylonwalker-com/ and k8s/rhiannonwalker/source-seed-job.yaml for historical builder images. Separate cosmetic renaming from functional Kubernetes resource changes.
Python archival: verify Python source/issue/docs URLs and Cloudflare pages deployments point to markata-py. Preserve old Python tags, import namespace and current installations. Plan PyPI markata-py distribution/alias separately rather than overwriting markata with an untested Go wrapper.
Ongoing 0.x validation: check old/new CLI parity on representative sites, installer compatibility, archive formats, Go consumers, Docker/Helm production smoke, registry permissions and GitHub source paths. Snapshot packaging can be tested without publishing a release. Any versioned tag requires a separate explicit decision; no 1.0 release or release candidate is planned as part of the rename.

Tracker: https://github.com/WaylonWalker/markata/issues/1628

Write your first post

2026-10-18T00:00:00Z

You don’t need templates or plugins to start. Markdown is the source. Markata turns it into pages.

Create a post #

From your site directory:

markata new "Hello, internet"

This normally creates pages/post/hello-internet.md. Open it in your editor.

You’ll see YAML frontmatter between two --- lines. The body is ordinary Markdown.

---
title: "Hello, internet"
date: 2026-10-18
published: true
draft: false
tags: ["notes", "web"]
description: "My first post with Markata."
---

Hello, internet. I'm building a little corner of the web.

## Why this exists

I want somewhere to write and share what I'm learning.

Here's **bold text**, a [link](https://example.com), and a list:

- Make something small
- Publish it
- Improve it later

Keep the frontmatter simple: title, date, published, draft, and optional tags are enough to begin. Markata can infer a slug, and additional frontmatter fields are available to templates.

Preview your words #

markata serve

Visit http://localhost:8000. Save your post; the development server rebuilds it. The page URL depends on your slug and theme configuration.

Draft before you publish #

markata new "An unfinished idea" --draft

For an existing post, set draft: true. To publish, set draft: false and published: true, then rebuild. Draft handling also depends on feed filters: do not assume a draft is publicly hidden if you override the default feed configuration.

Links and pictures #

Use ordinary Markdown for external links and images:

[My favorite reference](https://example.com)
![A description of the photograph](/images/my-photo.jpg)

Place site assets in static/ according to your configured assets directory. Check the emitted URL in the browser.

Markata also supports wikilinks for your own posts:

I wrote about this in [[hello-internet]].
Read [[hello-internet|my first post]].

Use a matching target slug. Prefer a normal link when sending someone to an external site.

Organize later #

Add tags when they’re useful. Use Feeds for collections, archives, and RSS; Themes for visual changes; and Templates for layout overrides.

Don’t start by writing a plugin. First ask whether frontmatter, config, an existing feed, or a template already does what you need.

Writing with an agent #

After installing the skill, a safe first request is:

Make a draft in the existing posts directory from these notes. Keep my voice, use simple frontmatter, and don’t publish anything yet. Validate config and run markata build --fast when done.

Review the result yourself before changing draft or deploying.

Ship it #

markata config validate
markata build

Upload the generated output/ directory to your static host. Follow Deployment, or return to the Quickstart.

Give your agent the Markata skill

2026-10-18T00:00:00Z

Let’s be honest: a lot of websites get built alongside coding agents. Give the agent the instructions that ship with Markata, rather than a stale prompt found in a chat.

The skill is bundled with the Go binary; you don’t need a separate installer or a proprietary cloud service.

1. Open your site repository #

cd my-site
markata agent list-agents

This prints the agent identifiers and their project/global skill locations. Supported harnesses include OpenCode, Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, and more.

2. Install the skill #

Use auto-detection (fallback: portable .agents/skills/markata-go-site/):

markata agent install

Or choose your harness explicitly:

markata agent install --agent opencode
markata agent install --agent claude-code
markata agent install --agent codex

For a specific agent, use --agent. For Claude Code, the project skill goes in .claude/skills/markata-go-site/; for a universal project install, it goes in .agents/skills/markata-go-site/.

The setup alias also installs the skill. On an interactive terminal, either command lists detected agents and asks whether to install for all of them. Press Enter or y to accept. Enter n to choose an agent from the fuzzy picker. If no agents are detected, the picker opens directly. Agents that share a skill directory use one installation.

For a global installation, use:

markata agent install -g

The picker uses an fzf-style layout: the prompt stays at the bottom, with results above it. The selected agent and matching characters use the terminal theme colors.

Type an agent name or abbreviation, such as copilot or ghcp. Use the arrow keys to navigate. Press Enter to select. Escape or Ctrl+C cancels without an installation. --no-color or NO_COLOR disables the colors. If an install for multiple agents fails, the error identifies the failed agent. Installations completed before the error remain in place.

For scripts, project installs keep the environment-detected agent or universal fallback. Global installs need an explicit agent:

markata agent install --agent opencode --global
markata agent install --agent github-copilot --global

The picker requires interactive input and output terminals. With --no-input or TERM=dumb, an explicit --agent is required. Unknown names show suggestions, such as Did you mean --agent github-copilot? for --agent copilot. Suggestions do not select an agent automatically.

3. Check it #

markata agent doctor

On a Markata upgrade, bring your skill up to date:

markata agent update
markata agent doctor

Use --dry-run on install or update to preview paths, or markata agent install --force to overwrite local customizations.

4. Start with a small instruction #

Read the installed Markata site skill and the current configuration. Create a draft Markdown post about what this site is for. Do not change the theme, plugins, or deployment setup. Show me the file and run a fast build to check it.

Agents can inspect the site with:

markata config show
markata list posts
markata explain content
markata build --fast

For rich content with symbols like :lucide-rocket: or :lucide-database:, responsive icon cards, or status/reporting blocks, the bundled skill includes topics/rich-markdown.md. Ask the agent to read that topic before creating new CSS, templates, or JS. The built-in icon syntax is documented under Icon Shortcodes.

Keep a human in the loop for publishing and deployment. Markata’s skill guides agents through frontmatter, themes, feed patterns, templates, site builds, and when not to create a plugin.

Visualize a session or topic #

After you install the skill, ask your agent:

Visualize this session.

The agent creates a visual Markdown post from the conversation’s work, decisions, and unresolved items. It serves a local preview, checks the exact post URL, and attempts to open that URL in your browser. The handoff includes the Markdown path, preview URL, browser-open result, and server handle or stop instruction.

For supplied material, use either phrase:

Visualize this: our release process starts with a draft, then review, then approval.

Make a visual post from these notes.

These are natural-language instructions for the agent, not Markata CLI commands. Ordinary chart, diagram, or styling requests do not automatically start a preview server.

For Markdown without a preview, state that constraint:

Visualize this session. Source only: create exactly one Markdown file.

The agent then creates the file without a server or preview scaffolding. Outside a Markata site, a full preview uses an isolated temporary site. The agent keeps that scaffolding outside your repository.

Local preview does not authorize public publication or deployment. The agent preserves publication flags and excludes secrets. The agent reports browser or persistent-server limitations instead of claiming that the page opened. On a remote machine, the preview can require port forwarding to reach your browser.

The workflow lives in the bundled skill’s topics/visualize-session.md. For an existing installation, use markata agent update after you install a binary with the updated skill.

Fixes #

If the wrong harness is detected, pass --agent explicitly.
If no skill is found, run markata agent install --dry-run and check the reported destination.
After upgrading the binary, run markata agent doctor and then markata agent update.
Keep the installed skill with your site’s source control when you want a reproducible project setup.

Next: Write your first post or Quickstart.

Getting started with Markata

2026-10-18T00:00:00Z

Getting started #

You do not need to learn the entire plugin system before publishing something.

Your first hour: install, create a directory, write one Markdown post, then build.

Install Markata — pick your operating system or installer.
Run the quickstart — markata config init, markata new, markata serve.
Install the bundled agent skill — let your agent work from accurate site-specific instructions.
Follow the authoring guide — posts, drafts, tags, links, and images.
Deploy the output — static hosting needs no Markata process in production.

Later, explore themes, feeds, templates, and plugins.

Markata is the Go project at WaylonWalker/markata. It is still 0.x. The original Python product lives at WaylonWalker/markata-py, and current PyPI releases install the Go CLI after a version break. Older Python versions remain available when pinned; see installation.

Markata naming migration

2026-10-16T00:00:00Z

The Go static site generator formerly known as markata-go is now Markata. The repository rename is complete, but Markata remains on the 0.x release line; the name change does not imply a 1.0 release. The original Python implementation is now at WaylonWalker/markata-py.

What works now #

New development builds provide the preferred markata executable. The legacy markata-go command remains supported, including existing tagged downloads. The official install script attempts a canonical archive and falls back to a legacy release where needed, installing both command names. If a different application (including Python Markata) already owns the markata command at the destination, the installer stops rather than overwriting it. Move the conflicting executable or choose a separate install directory.

curl -sSL https://raw.githubusercontent.com/WaylonWalker/markata/main/install.sh | bash
markata --help
markata build

# Existing automation still works:
markata-go build

If you install from Go source rather than binary releases, the new command is available from main until the first tagged version with the new entry point:

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

Configuration stays as-is for now #

There is no immediate need to rename configuration:

# markata-go.toml remains correct during the compatibility window
[markata-go]
output_dir = "output"

MARKATA_GO_OUTPUT_DIR, MARKATA_GO_SITE_DIR and other existing MARKATA_GO_* overrides continue working. Configuration overrides applied by the Go config loader also accept the canonical MARKATA_* aliases, for example MARKATA_OUTPUT_DIR. The canonical name takes precedence if both are set; conflicting values record name_migration_warnings on the loaded config (without exposing the values). Other runtime-specific settings may still use legacy names; migrate those only after their individual support is verified.

Renaming the config file to markata.toml or the TOML section to [markata] is not yet supported by the Go CLI, and may be confused with an original Python Markata configuration. Keep existing TOML filenames/sections for now.

For the installer, MARKATA_INSTALL_DIR and MARKATA_VERSION are preferred; the legacy MARKATA_GO_INSTALL_DIR and MARKATA_GO_VERSION still work.

GitHub repository cutover completed #

The repository swap was completed on October 18, 2026. The Go implementation is now WaylonWalker/markata (repository ID 1140034778); the original Python implementation is WaylonWalker/markata-py (repository ID 333449359). The old Go GitHub URL may redirect to the canonical Go repository, but use the new URL explicitly in new automation. Old Python bookmarks targeting WaylonWalker/markata now land on Go.

Read the repository cutover runbook for the owner rename checks and post-cutover infrastructure audit. The GitHub rename alone does not migrate the Go module import path, Python PyPI ownership, legacy configuration names, container registry permissions, or live sites.

Package and production migration #

The Go module now declares github.com/WaylonWalker/markata, and tracked Go imports have migrated to that path. Pinned pre-cutover releases may still be available under the old github.com/WaylonWalker/markata-go module identity. Avoid mixing both module paths in a single dependency graph. For new Go code and go install, use github.com/WaylonWalker/markata. See the Go module cutover guide for migration details.

Existing markata-go.toml, [markata-go], MARKATA_GO_*, markata-go binaries and legacy GHCR builder references are intentionally preserved. Do not rename Kubernetes PVCs, Helm release names or secrets merely to match branding. Audit Argo CD chart repo URLs and permissions separately, and verify published image compatibility and live workloads before changing production images. No new release tag is implied by the rename.

Slow 3G Harness A/A Validation on WaylonWalker.com

2026-10-13T00:00:00Z

Slow 3G A/A validation #

This report validates PR #1554 against a fresh build of the actual WaylonWalker.com working source. These are A/A measurements for harness noise and filmstrip inspection. No site optimization was included, so this report makes no A/B performance claim.

Pinned inputs #

Site source commit: 82ae5bcfc67674abfd2e5a169ca9551e2255ff57 with local working-tree edits and untracked site posts included in an isolated snapshot.
SHA-256 of the exact copied build-input tree: ba2a97aa9f0b4a870555c19c6b5bcf3e055b59e34f8567c46449feedbbfca346.
Markata Go build revision: 0af03c725fecacec934ba1d51649ca7a86155e01.
Harness capture revision: fd66fbd0eb1480a69a5ea2dbebac93d5cb28d9e5.
Browser: Chromium 153.0.8010.52; Playwright from the harness PEP 723 dependency declaration; Python 3.14.7.
Fresh generated output: 3,540 discovered posts, 3,518 rendered, 421 feeds; build completed in 45.35 seconds. Output size was 2.4 GiB.

The site checkout contains private encrypted source. Its configured MARKATA_GO_ENCRYPTION_KEY_* values were passed directly from the local .env to the isolated build process. Secret values were not recorded. The snapshot excluded .env, Git metadata, previous output and build caches.

Capture setup #

The same generated output directory was served from ports 8000 and 8001 with scripts/slow3g_site_server.py. Each browser run used a new context, disabled the browser cache and used the harness defaults: 390×844 viewport, 400 ms latency, 51,200 bytes/second up and down, and 4× CPU slowdown. Each route ran five alternating A/B and B/A pairs, with a 16-second observation window and frames requested at 1, 2, 5, 8, 12 and 15 seconds. The A and B labels refer to the two server ports; both serve identical bytes.

Results #

Median values below are across five valid runs for each port. Encoded bytes are completed transfers during the 16-second window, not bytes received at paint. First-readable times are manual estimates from the saved frames, rounded to the checkpoint interval.

Route	Valid runs per port	Median FCP A/B	Median LCP A/B	Median CLS A/B	Median bytes A/B	Median requests A/B	First readable main content
`/`	5/5	6292/6204 ms	6292/6204 ms	0.010765/0.010765	613690/613514	66/66	About 8 s; intro/about text is visible.
`/archive/`	5/5	5120/5136 ms	7504/7392 ms	0.000337/0.000337	301620/301582	32/32	About 8 s; first post title and snippet are readable.
`/blogging-for-me/`	5/5	4072/4064 ms	4280/4276 ms	0.010112/0.010112	372229/372229	47/47	By 5 s; article title and opening paragraph are readable.
`/shorts/`	5/5	972/972 ms	2848/2836 ms	0.006164/0.006164	53185/53178	8/8	By 5 s; the image is sharp and its “Bat Cap” title is readable. At 2 s the media is still blurred.
`/reader/`	0/5	—	—	—	—	—	The 5 s frame shows the Reader heading and an empty-state message, with 0 entries. Runs are invalid as described below.

Median absolute paired FCP differences for the four valid routes were 84 ms (home), 88 ms (archive), 24 ms (article) and 8 ms (shorts). Median absolute paired LCP differences were 84 ms, 224 ms, 40 ms and 36 ms respectively. These describe same-build measurement variability; they are not performance gains. Archive request counts varied between 32 and 57 in individual runs, which is one reason to inspect raw results.json instead of relying only on the medians.

Largest completed resources observed included the gzip archive document at 266,979 bytes, source-sans-3-prose-core.woff2 at 79,495 bytes, caveat-brush-display-core.woff2 at 47,883 bytes, the local /8bitcc.png at 56,890 bytes, and the shared palette CSS at 30,787 bytes. The home and shorts routes also fetched images from dropper.waylonwalker.com; those remain external to the local test server. Per-request encoded and decoded transfer lengths, URLs, types and completion state are retained in each results.json.

Invalid reader route #

All ten reader runs were marked invalid. The freshly generated reader/index.html requests /_pagefind/pagefind-ui.css and .js, but this output has neither file; the server correctly returns 404 with HTML MIME. The harness records two failed requests and two invalid asset responses per run. This is missing output from the site build, not a reason to suppress the harness checks. Also, the fresh page contains zero reader entries, so it does not represent a populated production reader. Reader timings are excluded from the table and from any noise estimate.

Reproduction #

Use a clean snapshot of the same site source state, including the intended working-tree content changes. Keep .env out of the snapshot and provide the site’s encryption keys only to the build process through environment variables. Pin the Markata Go and harness revisions above.

rsync -a --delete \
  --exclude='.git' --exclude='.env' --exclude='.env.*' \
  --exclude='output/' --exclude='cache/' --exclude='.markata/' \
  --exclude='.markata-cache/' --exclude='.steam_cache/' \
  --exclude='.output.markata-serving/' --exclude='node_modules/' \
  "$SITE_CHECKOUT/" "$SITE_SRC/"

git -C "$MARKATA_REPO" worktree add --detach "$MARKATA_BUILD" \
  0af03c725fecacec934ba1d51649ca7a86155e01
go -C "$MARKATA_BUILD" build -o "$MARKATA_BIN" ./cmd/markata-go

"$MARKATA_BIN" build --clean \
  -c markata-go.toml \
  --site-dir "$SITE_SRC" \
  -o "$SITE_OUT"

python scripts/slow3g_site_server.py --root "$SITE_OUT" --port 8000
python scripts/slow3g_site_server.py --root "$SITE_OUT" --port 8001

uv run --script scripts/slow3g_compare.py \
  --chromium /usr/bin/chromium \
  --before http://127.0.0.1:8000/ \
  --after http://127.0.0.1:8001/ \
  --runs 5 --observe-ms 16000 --timeout-ms 26000 \
  --checkpoints 1000 2000 5000 8000 12000 15000 --min-frames 5 \
  --output docs/reports/slow3g-1554/aa-home

Repeat the capture command with both route URLs changed to /archive/, /blogging-for-me/, /shorts/ and /reader/, and use separate output directories. Inspect the saved filmstrip.html and frames for readability. Keep failed requests and wrong-MIME responses in the report as invalid runs.

Preserved artifacts #

Each aa-* directory contains results.json, summary.json, summary.csv, filmstrip.html, all 60 requested checkpoint frames and the contact sheets used for the manual readability review. The reader directory preserves its failed requests and invalid-asset diagnostics as well.

Editorial history

2026-10-11T00:00:00Z

Keep the writer prominent while giving every editor credit. The default theme shows editors below the author byline. The first credited editor is visible; additional editors appear in a compact avatar stack that expands to show their names and roles. Credit order follows the post’s authors list. Editing and reviewing roles, including copy editor, internal-link-editor, editor, and writing-review-editing, are grouped as editors. Coauthors keep their original order and prominence.

authors:
  - waylon
  - id: copy-editor-agent
    role: copy editor
  - id: linking-agent
    role: internal link editor

Configure contributor names and avatars as described in Authors. The native editorial authoring commands can commit selected human or agent edits and fill in the revision history automatically.

Record a revision #

Add an event to editorial_history after committing an editor’s changes. Keep previous events. Each event points to one file at one exact revision, even when a commit edits several posts.

editorial_history:
  - schema_version: 1
    event_id: "session-id:pages/blog/example.md"
    author: copy-editor-agent
    role: copy-editor
    action: edited
    recorded_by: copy-editor-agent
    recorded_at: "2026-10-11T15:00:00Z"
    base_commit: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
    commit: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
    path: pages/blog/example.md
    file_url: https://github.com/OWNER/REPO/blob/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/pages/blog/example.md
    summary: Corrected spelling and grammar.

Replace the example SHAs with real full 40-character commit SHAs and the URL with the matching repository and file. Use action: reviewed for an unchanged review. Set recorded_by to the importer when someone else records existing work; the page displays that distinction. The native tools also record digest fields, diff URLs, and event IDs for later automation. The viewer does not claim that a historical review covers today’s content.

Inspect changes #

The built post has a collapsed Editorial history section, newest event first. Each entry identifies the contributor, role, action, timestamp, summary, and commit. Readers can open the exact file or its diff in GitHub. These links and the history work without JavaScript.

For edit events with valid before and after revisions, Show changes here loads a small comparison viewer and fetches those two files directly from GitHub. Added words are underlined and removed words are struck through. The viewer compares historical Markdown source, excluding YAML frontmatter. Markdown syntax remains visible; it does not execute historical HTML or reconstruct ownership of the current rendered article. A change affecting only frontmatter reports that no Markdown body changes occurred.

Revision fetching starts only after a reader clicks the comparison control. The build does not contact GitHub or require the site’s full Git history. The viewer has no third-party script dependency, limits each file to 512 KiB, and caps comparison work for extensive rewrites. Large rewrites may highlight a whole changed passage rather than each word.

Push the recorded commits before publishing their links. Private repositories, missing revisions, offline connections, and restrictive content security policies can prevent inline comparisons. Readers can retry or open the GitHub diff with their own account. No credentials are sent to GitHub by the inline viewer. For a CSP, allow the site’s own scripts and styles and permit connect-src https://raw.githubusercontent.com for inline comparisons.

Custom templates #

The normalized template fields are post.editorial_history_view, post.byline_authors, post.byline_editors, and post.additional_editor_count. The original post.author_objects and post.Extra.editorial_history remain available. The default template uses components/editorial_history.html; sites overriding post.html should include that component and conditionally load css/editorial-history.css and js/editorial-history.js when normalized history exists. Asset paths should use theme_asset_hashed. The component supplies the heavy viewer’s hashed asset URL for loading only on demand.

Malformed records and unsupported schema versions are skipped. Unsafe or mismatched revision coordinates leave metadata without executable links. GitHub diff links are rebuilt from validated file coordinates, so they always target the recorded file in the recorded commit.

Attributed editorial authoring

2026-10-11T00:00:00Z

Editorial authoring #

Use the editorial commands when a person or agent is editing a post and the result needs a durable author, role, commit, and GitHub link.

Start a session from clean tracked Markdown files:

markata-go editorial start posts/my-post.md \
  --author editor-id --role copy-editor

Edit the files, then finish the session:

markata-go editorial finish --session SESSION-UUID \
  --summary "Corrected grammar and tightened headings"

An edited session creates two owned commits. The first contains the post edits and contributor credit. The second appends an editorial_history event with the exact file URL, diff URL, commit SHA, digest, role, and summary. Unchanged posts are recorded as reviews with a metadata commit only.

For changes that already exist in the working tree, use the explicit commit path:

markata-go editorial commit posts/my-post.md \
  --author linker-id --role internal-link-editor \
  --summary "Added links to related posts"

Selected staged changes are rejected so ownership is explicit. Other staged and unstaged files stay in place. Add --json for automation or --dry-run to validate inputs without changing the repository.

When a post has no author or authors field, the command uses the configured default author when one is marked in the site’s author configuration. You can override it explicitly with --primary-author writer-id; the editor is never silently promoted to the post’s primary writer.

When an agent runs commands for a human who wrote the edits, keep the human’s ID in --author and use --recorded-by for the agent’s ID:

markata-go editorial commit posts/my-post.md \
  --author alex --role copy-editor --recorded-by agent-model-id \
  --summary "Alex corrected grammar"

The content commit credits Alex; the attribution commit credits the recorder. The built history shows that distinction. For a session, supply --recorded-by when starting it; the recorder ID is retained for finish and retries.

Adaptive Loading Hardening

2026-10-08T00:00:00Z

An audit of the existing full-document View Transition navigator found that it could reset loading attributes to server defaults. The final follow-up preserves those attributes, initializes new-route authored media, and restarts a bounded timing window on its existing completion event. Chromium integration exercises that actual navigator for Auto and both manual modes. The CDP/Lighthouse tables below measure checkpoint aa86d8ec; this route-entry follow-up adds about 68 gzip bytes to the controller and runs on subsequent route completion, not initial paint. Initial-load policies and representative media markup are unchanged.

Issue #1524, existing feat/adaptive-client-loading branch. This continues the design and implementation commits rather than replacing their architecture.

Benefit #

The final controller is 12,072 source bytes, 6,408 generated/minified bytes, 2,393 bytes gzip (level 6), and 2,125 bytes Brotli. The generated main stylesheet delta is 2,134 bytes uncompressed and 433 bytes gzip. One deferred controller request is added; CSS uses the existing request. Overall route request counts also reflect removed optional player assets.

Real HTTP transfer tests prove deferred startup before load, timing collection with PerformanceObserver and Network Information disabled, constrained Auto, four-good recovery, offline/online hysteresis, manual precedence, mismatch Keep/Use Auto actions, unchanged loaded image sources, stable video geometry, and no playback restart. Cached images cannot masquerade as fast network measurements. A page stops after twelve votes; another page can provide new measurements. Generic healthy 4g hints cannot erase measured poor confidence; browser Save Data intent keeps Auto constrained even with fast measurements.

CDP repeat measurements #

Each cell is a median of three fresh contexts. Network Information is disabled; Auto has no manual preference or seeded confidence. Mobile is 390×844, with 150 ms latency and 192 KiB/s downstream for constrained cases. Desktop is 1365×900. Feed/image routes receive the same four 700-pixel scrolls. LCP and CLS are captured before scrolling; transfer totals include exploration.

Baseline is 73c4f606. Final candidate after-runs were repeated after reserving poster geometry. All runs use gzip responses from the same local server and live external media, with a 2.5-second post-load observation window. Baseline and candidate are built from an isolated copy of the current real site’s inputs, including its local edits, with separate cache/output directories. The source site is unchanged. Encryption is disabled equally for both builds; Searchcraft index publication is disabled. These totals are not directly comparable to the older report’s server/compression setup. First-party inputs and build output are deterministic; external media and server redirect latency still vary.

Raw per-run metrics, paint attribution, confidence, and aborted requests are in docs/reports/adaptive-loading-hardening-results.json. Aborted baseline video requests are included in request counts; totals include completed CDP transfers. This is a bounded observation window, not the lifetime download volume.

Mode	Route	Bytes before → after	Requests	Media bytes	LCP seconds	CLS	Final policy
auto-constrained	/vimgrep-open-buffers/	652,982 → 649,995	50 → 49	0 → 0	1.344 → 1.812	0.0266 → 0.0276	constrained
auto-constrained	/til/	723,982 → 688,951	63 → 56	32,520 → 0	1.420 → 1.412	0.0674 → 0.0681	normal
auto-constrained	/2025-nas/	1,334,700 → 1,331,512	60 → 59	0 → 0	3.996 → 3.952	0.0073 → 0.0075	constrained
auto-constrained	/tmux-pop-size/	1,387,406 → 886,531	57 → 57	502,099 → 0	4.044 → 4.036	0.0073 → 0.0075	constrained
auto-constrained	/bloatware-is-dying/	766,187 → 763,718	60 → 57	0 → 0	2.844 → 2.948	0.0109 → 0.0111	constrained
auto-normal	/vimgrep-open-buffers/	652,978 → 649,995	50 → 49	0 → 0	0.672 → 0.428	0.0072 → 0.0071	normal
auto-normal	/til/	952,811 → 688,694	60 → 56	261,857 → 0	0.732 → 0.560	0.0618 → 0.0071	normal
auto-normal	/2025-nas/	1,334,030 → 1,331,506	60 → 59	0 → 0	0.760 → 0.444	0.0072 → 0.0071	normal
auto-normal	/tmux-pop-size/	1,387,390 → 886,532	57 → 57	502,099 → 0	0.776 → 0.472	0.0072 → 0.0071	normal
auto-normal	/bloatware-is-dying/	1,539,251 → 763,718	60 → 57	773,075 → 0	0.992 → 0.520	0.0072 → 0.0071	normal
save-data-constrained	/vimgrep-open-buffers/	652,998 → 649,995	50 → 49	0 → 0	1.632 → 1.536	0.0266 → 0.0279	constrained
save-data-constrained	/til/	723,756 → 688,683	63 → 56	32,512 → 0	1.520 → 1.400	0.0674 → 0.0702	constrained
save-data-constrained	/2025-nas/	1,334,510 → 1,331,521	60 → 59	0 → 0	3.932 → 3.972	0.0073 → 0.0084	constrained
save-data-constrained	/tmux-pop-size/	1,387,402 → 886,536	57 → 57	502,095 → 0	4.044 → 4.040	0.0073 → 0.0084	constrained
save-data-constrained	/bloatware-is-dying/	766,187 → 763,718	60 → 57	0 → 0	2.772 → 2.988	0.0109 → 0.0141	constrained
desktop-normal	/vimgrep-open-buffers/	652,986 → 649,995	50 → 49	0 → 0	0.724 → 0.548	0.0000 → 0.0000	normal
desktop-normal	/til/	953,124 → 688,679	61 → 56	262,085 → 0	0.848 → 0.904	0.0342 → 0.0052	normal
desktop-normal	/2025-nas/	1,334,502 → 1,331,513	60 → 59	0 → 0	0.812 → 0.484	0.0000 → 0.0000	normal
desktop-normal	/tmux-pop-size/	1,387,905 → 886,530	58 → 57	502,096 → 0	1.504 → 0.960	0.0138 → 0.0000	normal
desktop-normal	/bloatware-is-dying/	1,539,761 → 763,718	61 → 57	773,093 → 0	1.012 → 0.592	0.0052 → 0.0058	normal

Auto independently detects the constrained profile on the text, image-heavy, video, and embed routes. The feed has only one usable poor sample and remains Normal: many remote media responses omit Timing-Allow-Origin. It still saves about 35 KB and seven requests through the conservative static policy. This is not a claim that Auto classified the feed as constrained. Auto normal also stays Normal when there are fewer than four actual good media/navigation samples; generic 4g alone does not grant autoplay.

Constrained video avoids approximately 501 KB total and 502 KB media transfer. Constrained embed transfer is essentially unchanged (about 2.5 KB less), with three fewer requests; that baseline did not transfer embed media in the window. Normal embed runs do show substantial deferred media savings. The controller cost and media savings are separate measurements.

Lighthouse (separate method) #

Lighthouse 12.8.2 mobile simulated throttling, performance category, Chromium. Comparable before/after configurations; these are snapshots for four routes, and three-run medians for video. Never subtract these from CDP measurements. Totals and counts come from Lighthouse network-requests, including redirects.

Route	LCP seconds	CLS	Total bytes	Media bytes	Requests
text	4.956 → 5.105	0.0000 → 0.0000	652,988 → 649,995	0 → 0	50 → 49
til	5.482 → 5.189	0.0000 → 0.0647	5,214,156 → 689,525	4,522,564 → 0	60 → 56
2025-nas	7.385 → 6.382	0.0000 → 0.0075	1,334,327 → 1,331,554	0 → 0	60 → 59
video	6.157 → 6.229	0.0000 → 0.0086	1,387,879 → 887,168	502,101 → 0	57 → 57
bloatware-is-dying	5.855 → 5.708	0.0000 → 0.0075	1,540,179 → 763,718	773,608 → 0	60 → 57

Video LCP and stability #

The original 10.78 → 13.85 s constrained regression did not reproduce. Final constrained CDP video medians are 4.044 → 4.036 s; desktop is 1.504 → 0.960 s. Absolute times changed with response compression and harness conditions, so this establishes a comparable local delta, not a universal speedup. Mobile’s measured LCP is a paragraph, while desktop may count a video frame or its new poster. First candidate desktop medians were 1.50 → 1.56 s, with substantial per-run variance.

A Lighthouse trace shows the poster API request returning a 307 after about 629 ms, followed by a 78 ms, 3.3 KB thumbnail response. Both poster and video requests were Low priority; poster work starts earlier, not later. This redirect/server latency explains why a tiny poster can still be a late desktop paint. No evidence attributes the old regression to controller initialization. The historical run lacks a trace, so its exact cause cannot be established.

Layout-shift attribution identified content below the unsized video moving when the poster arrives. Reserving a 16:9 frame for derived 1200×675 posters removed that shift in final desktop video runs (CLS about .00002). Raw authored height/inline styles remain authoritative. Loaded images are not replaced and policy updates do not pause, rewind, reload, or replace actively requested media. The controller does not enable animations in response to improved connectivity. Small mobile font/layout shifts remain site-level baseline behavior.

Tradeoffs #

Generic network hints bootstrap conservatively rather than declaring a fast connection. Timing needs useful same-origin/Timing-Allow-Origin transfers; opaque, cached, tiny, and neutral-rate resources do not vote. Observations end after thirty seconds or twelve votes, so later changes may require another page. No continuous polling or framework is added. Session confidence expires after ten minutes. The new observer adds bounded lifecycle work for late resources.

Explicit raw autoplay and configured Markdown autoplay survive as data-authored-autoplay="true". Full Quality or measured fast Auto at page entry can start unrequested authored media. Fresh fast evidence during a page view affects subsequent pages and does not suddenly animate an existing poster. Save Data, unknown/Normal/constrained Auto, and reduced motion suppress automatic playback. Raw video without autoplay never inherits it merely from site-wide config. Native controls and sources remain. With JavaScript disabled, authored autoplay also requires interaction: this is the deliberate conservative-baseline tradeoff. Browser autoplay permissions can still reject playback; the controller does not retry or restart it.

Chromium, Firefox (installed Playwright Firefox 1511), and Brave integration passed with missing Network Information, real timing fallback, all user modes, mismatch UI, video interaction, recovery, offline/online, sample caps, and cache exclusion. Brave’s Network Information is deliberately disabled in the portable path tests; this is not a claim about every privacy setting. Safari/iOS were not run. No broader device study is claimed.

Readiness #

Adaptive loading: READY FOR PR after the recorded validation and clean commit.

go test ./... passes using disk-backed TMPDIR.
node --test scripts/adaptive-loading.test.cjs: 13 pass.
node --test scripts/adaptive-loading.browser.test.cjs: Chromium/Firefox/Brave pass.
just lint-new, go fmt ./..., and git diff --check pass.
Generated controller stays below the 3 KB gzip ceiling.
Spec, configuration/plugin/user docs, and bundled site-agent guidance updated.

Initial test/build attempts hit the temporary-filesystem quota, and a moved output root was rejected as a symlink. Those incomplete builds and failing runs are discarded. Final corpus builds use direct disk paths; final checks use disk-backed temporary files. No unrelated heading_anchors change was made.

Next steps #

Review the focused adaptive branch without merging. Keep the poster redirect as a measured deployment/media-service follow-up rather than expanding this controller. Recheck on Safari/iOS when a real device is available. Investigate partial navigation separately only after this readiness gate.

Reproduction #

adaptive-loading.benchmark.cjs BEFORE_URL AFTER_URL RESULTS.json runs three fresh contexts per mode/route. Serve both output trees with identical gzip handling; the historical Python plain-file server is not the same measurement configuration. Optional BENCHMARK_MODES, BENCHMARK_ROUTES, and BENCHMARK_VERSIONS limit reruns. The browser integration test uses Playwright bundled with agent-browser, or PLAYWRIGHT_MODULE for another installation. Set ADAPTIVE_FIREFOX_EXECUTABLE when the installed Firefox path differs from the Playwright version’s default. Test SVGs use real delayed server responses, not injected vote/state samples. The tiny WebM fixture is a three-second, 160×90 blue frame generated with FFmpeg/libvpx-vp9; it tests actual media playback.

Keep native controls enabled (or supply an accessible play action) for deferred videos. A video deliberately authored without controls needs its own interaction path in Save Data and no-JS mode; autoplay intent alone is not a play control.

Adaptive Client Loading Benchmark

2026-10-07T00:00:00Z

Historical measurements from implementation commit bbb5cb53. The hardening report supersedes its policy, autoplay, browser coverage, and readiness findings. See Adaptive loading hardening.

This report records browser measurements before and after adaptive client loading on the real waylonwalker.com corpus. The source site was not edited. Both builds used the worktree binary and wrote to temporary output directories.

Reproduce #

The site normally builds with just build, which runs markata-go build -m config/no-tailwind.toml. The benchmark used the same site and config with a separate output path and cache:

markata-go build --site-dir ~/git/waylonwalker.com \
  -m ~/git/waylonwalker.com/config/no-tailwind.toml \
  -o /tmp/markata-adaptive/output

Serve the output with python3 -m http.server 8766 --directory /tmp/markata-adaptive/output. The Chromium harness used Puppeteer already bundled with Lighthouse, 390×844 with 150 ms latency and 192 KiB/s downstream for mobile, and 1365×900 without shaping for desktop. The constrained run selected Save Data in local storage and rapidly scrolled the feed. Counts and byte totals are CDP transferred bytes, including responses captured during that scroll. LCP and CLS are from the same short run and are directional; the rapid scroll and third-party timing make CLS especially noisy. DOM text is the number of body text characters available at DOMContentLoaded, not a paint timestamp.

Representative mobile run #

Page	Before requests / bytes	After requests / bytes	Before / after media bytes	Before / after LCP	Before / after CLS
Text article `/vimgrep-open-buffers/`	50 / 1,401,880	49 / 1,405,312	0 / 0	5.90 / 5.93 s	.0074 / .0086
Feed `/til/` after rapid scroll	63 / 1,604,478	55 / 1,578,159	32,513 / 0	5.91 / 5.51 s	.442 / .395
Video article `/tmux-pop-size/`	57 / 2,843,230	55 / 2,348,743	501,728 / 0	10.78 / 13.85 s	.0074 / .0086
Embed article `/bloatware-is-dying/`	60 / 2,252,247	57 / 2,255,430	0 / 0	9.74 / 9.78 s	.056 / .0082

The text article added about 3.4 KB net and one fewer request. Across the four pages, JavaScript transfer increased by 1.3–1.4 KB; the generated controller is 5,281 bytes uncompressed and 2,031 bytes gzip. It is deferred, non-blocking, and shares the existing page CSS. The video article avoided about 494 KB total, including its 502 KB autoplay transfer, while adding a right-sized poster. The feed avoided 26 KB net and eight requests in this particular rapid-scroll pass. Its remaining images still load as native lazy images when scrolling brings them near the viewport.

The embed page did not transfer media in either CDP run; this run therefore does not support a media-savings claim for that page. It did avoid three requests overall, while its byte total changed by about +3 KB. Its external embed behavior is timing-sensitive. The controller does not make claims about bytes that were not observed.

Desktop normal run #

Page	Before requests / bytes	After requests / bytes	Before / after media bytes	Before / after LCP
Text article	50 / 1,402,359	49 / 1,405,312	0 / 0	.93 / .59 s
Feed	59 / 1,605,506	53 / 1,577,633	32,165 / 0	.80 / .51 s
Video article	57 / 2,843,745	55 / 2,348,743	501,622 / 0	.83 / 1.45 s
Embed article	59 / 2,992,113	56 / 2,221,185	773,597 / 0	.62 / .52 s

The video article’s raw HTML previously autoplayed a remote MP4. It now keeps native controls and source markup but defaults to no autoplay and preload="none", so its poster is the initial visual. This accounts for the large stable transfer reduction on both desktop and mobile. The embed page’s desktop reduction is observed in this run; it should be rechecked against a second cache/network state before treating that amount as typical.

Lighthouse baseline #

Mobile Lighthouse baseline reports (12.8.2, simulated throttling) recorded 50 requests / 1.40 MB / 6.37 s LCP for the text page; 63 / 4.32 MB / 7.93 s for the feed (2.74 MB media); 57 / 2.85 MB / 11.86 s for the video page (502 KB media); and 60 / 3.00 MB / 11.42 s for the embed page (774 KB media). These are a separate measurement method from the CDP table above. A comparable post-change Lighthouse run was not captured, so no Lighthouse delta is claimed.

Stability and UX checks #

Chromium mobile and desktop generated pages kept article/card geometry stable when the policy changed. The Save Data video run made zero media requests; the generated HTML contained no autoplay, used preload="none", and retained a poster and native controls. A Chromium UI smoke check seeded a confident constrained recommendation with manual Full Quality selected: the small status affordance appeared, opened the settings panel with “Full Quality is on. Your connection appears constrained.”, and “Use Auto” cleared the local override. No full-page screenshot is included because the UI is a small native disclosure/status control rather than a separate screen.

The rendered controller gzip size is 2,031 bytes. The added CSS is part of the existing stylesheet (no extra CSS request); the appended rules gzip to roughly 0.5 KB. The control layer adds one script request on pages that do not already bundle it, but the site’s overall request count was flat or lower because optional player CSS and automatic external video loads were removed/deferred. No long-lived observer or polling loop is used; resource timing samples stop after six observations.

Browser coverage and limits #

Browser	Result
Chromium	Mobile constrained and desktop normal transfer runs; manual mismatch and Auto action smoke-tested.
Chrome	Not separately installed; Chromium run covers the shared engine behavior.
Brave	Not installed locally. Network Information API is optional and not required.
Firefox	Not installed locally. Portable resource timing, online/offline, and native loading paths are used without browser detection.
Safari/iOS	Not run. The baseline uses native image/video/HTML behavior and avoids reliance on Chromium-only APIs.

This is a local corpus benchmark, not a broad device study. Timing variation, browser cache state, third-party responses, and site-level autoplay configuration can affect totals. Sites that explicitly set [markata-go.md_video] autoplay = true retain that opt-in behavior. The primary tradeoff is that autoplay is no longer the default; readers press native video controls to start playback. More aggressive image deferral, embed-specific click facades, and a repeat Lighthouse after-run remain follow-up work.

Adaptive Loading

2026-10-07T00:00:00Z

Markata-Go sites keep article text available immediately and let the browser load images and video with native HTML behavior. Visitors can choose how much optional media work the site should do.

Choose a loading mode #

Open Loading in the site header and choose one of these modes:

Auto uses recent browser connection hints and a few real resource timings.
Save Data limits optional media work and speculative requests.
Full Quality allows optional work to begin sooner.

Auto is the default. A saved Save Data or Full Quality choice always takes precedence over Auto. The preference is stored in the current browser only.

What Auto does #

Auto uses navigator.connection when the browser exposes it, but the site works without that API. It also learns from a small number of recent navigation and resource timings. One slow image or request does not change the mode. Auto requires two meaningful transfers below 2 Mbps to constrain optional work and four consecutive transfers above 4 Mbps with low response latency to recover. Generic 4g/downlink hints initialize Auto but cannot erase measured evidence. Browser Save Data intent constrains Auto immediately. Each page observes at most twelve transfers for thirty seconds; later pages can provide fresh evidence. Offline constrains Auto immediately, and reconnecting needs fresh evidence. Suggestions require four poor observations for Full Quality or five good ones for Save Data.

If Auto becomes confident that your manual choice no longer fits the connection, a small status prompt offers Use Auto or Keep [mode]. Keeping or dismissing the choice quiets the prompt for the current session.

Media and JavaScript #

Images use browser-native loading and retain their dimensions while loading. Derived video posters reserve a 16:9 frame when the author has not supplied height or inline styling. Supply your own height/style for a different frame. Video previews show a poster and do not fetch the video until playback is requested. Article video keeps native controls and remains usable if JavaScript does not run. The adaptive script does not replace an image that is already visible or restart a video when the connection changes.

Markdown videos default to no autoplay and preload = "none". Raw HTML keeps explicit autoplay intent in data-authored-autoplay="true", while removing the native autoplay attribute and using preload none. Raw HTML without autoplay never gains it from the site-wide Markdown setting. To opt into GIF-like playback for site videos, set:

[markata-go.md_video]
autoplay = true
loop = true
muted = true
preload = "metadata"

The generated intent marker allows Full Quality or already-confident fast Auto at page entry to start authored autoplay. Save Data and constrained/unknown Auto leave the poster until interaction. Videos authored without autoplay stay manual in every mode. Reduced motion also prevents automatic playback. Changing policy does not pause, restart, or replace a video that has begun loading or playing. With JavaScript disabled, even authored autoplay requires pressing the native controls; this keeps the initial document conservative before a visitor’s preference is known.

The controller is a small theme asset. Video and embed helpers remain conditional, so a text-only page does not load a player just in case.

Auto honors authored autoplay when measured confidence is already fast at page entry. Learning that the network is fast during a page view affects subsequent pages; it does not suddenly animate an existing poster. An explicit Full Quality choice may start unrequested authored video on the current page. Active media remains untouched in either case.

The existing full-document View Transition navigator preserves loading-mode attributes and the persistent control. Each completed route initializes only its newly inserted authored media, expires stale session evidence, and opens a fresh bounded timing window. It does not rerun the controller or reset the visitor’s manual choice.

Feed Views

2026-10-02T00:00:00Z

Built-in feeds expose three presentation views by default: default, simple, and calendar. An opt-in fourth view, shorts, adds a full-screen photo/video player. default is the feed’s normal card/grid page and is always required. simple is the compact /simple/ page, and calendar is the interactive ?view=calendar peer view.

To disable an alternate view for every feed, set site-wide feed defaults:

[markata-go.feed_defaults]
views = ["default", "calendar"]

A feed can override that set:

[[markata-go.feeds]]
slug = "notes"
views = ["default", "simple"]

Omitting views inherits the site defaults. Unknown view names are configuration errors, and an explicit list must include default. Disabling simple also stops Markata from generating that feed’s /simple/ HTML output even when formats.simple_html is enabled. Disabling calendar removes Calendar controls and avoids loading its CSS, JavaScript, and hidden calendar source data. Output-format settings for RSS, Atom, JSON, Markdown, text, and sitemaps are independent of views.

An empty list is invalid. Config overlays replace the view list rather than adding to it. Keep default in every explicit list. Rebuilding after disabling Simple removes its stale generated /simple/ pages.

See feed configuration and the feed guide for pagination and output-format options.

Shorts view #

The Shorts presentation uses the existing feed’s selected posts and sort order, without copying the filter. To enable it for a Shots gallery:

[[markata-go.feeds]]
slug = "shots"
views = ["default", "simple", "calendar", "shorts"]
shorts_path = "/shorts/"

[markata-go.feeds.templates]
html = "feed-photo-grid.html"

The grid remains at /shots/, and the full-screen player is available at /shorts/. A URL fragment such as #id=shots%2Fdog identifies an individual post. The reader traverses the complete feed using static JSON chunks, independent of normal feed pagination. Only one video plays at a time; surrounding posts are loaded as previews. The previous and next buttons stay fixed at the right center of the screen, separate from the video controls. Use j/k or the up/down arrows to move, Escape to return to the grid, Space to play or pause a video, left/right arrows to seek five seconds, and m to mute or unmute.

If not configured, the Shorts route defaults to /<feed-slug>/shorts/. Only enable Shorts on a feed that should expose a full-screen player.

Adaptive HTML layouts #

The main HTML feed can use classic, editorial, gallery, reading, timeline, or resources. Select auto to choose from the feed’s post types. The default is classic to preserve existing sites.

[[markata-go.feeds]]
slug = "archive"
presentation = "editorial"

[[markata-go.feeds]]
slug = "ping"
presentation = "timeline"

[[markata-go.feeds]]
slug = "stars"
presentation = "resources"

Site-wide defaults may be set in [markata-go.feed_defaults] with presentation = "classic" (or a different layout). A feed’s own presentation overrides that default.

auto chooses a specialized layout when at least 80% of eight or more posts are photos, notes, links, or articles. Feeds with at least twelve posts and three content types represented by two posts each use editorial grouping. Smaller or unclassified feeds retain the classic view. Custom HTML templates, such as feed-photo-grid.html, take precedence over automatic layout detection.

Editorial grouping uses Monday-start publishing weeks. Weekly headings show relative calendar time (This week, Last week, 2 weeks ago, 2 months ago, 2 years ago) with the exact week range as a smaller caption. Relative labels are rendered at build time and refreshed in the browser so long-cached static pages remain accurate without a rebuild. Dates and weekly grouping remain unchanged. Articles are emphasized, substantial links and video follow, and all photos from a publishing week appear together in a single responsive gallery. One-photo weeks also use the gallery layout rather than stretching a photo into a full-width card. Each photograph retains its own publication date, caption, and permalink, even when photos come from different days. Brief notes are visually quieter. featured: true on a post explicitly elevates it within its week. Each post retains its original HTML card and metadata.

Presentation never modifies RSS, Atom, JSON, Simple, Calendar, source ordering, or the existing pagination boundaries. Weeks that span two HTML pagination pages continue on the next page. JS-pagination feeds keep classic markup because the JS paginator requires direct child cards.

Build Span Presentation Model

2026-10-02T00:00:00Z

Builder Admin has an internal span presentation model for future trace views. It converts completed build spans into rows ordered by start time, with nesting depth, integer millisecond timings, attribution, and copied attributes.

The highlighted completion chain follows the latest-finishing leaf and its ancestors. This is a timing heuristic; it does not calculate a dependency-aware critical path. Missing parents and cyclic parent links terminate traversal. Negative timings display as zero, and sub-millisecond timings round down.

The model does not yet expose a waterfall or trace API. Benchmark retention and operator UI integration remain follow-up work. For recorded span data today, see the performance guide.

Maintainer CI

2026-10-01T00:00:00Z

This guide describes CI for the markata-go product repository (issue #1487). For site-author deployments, use the [[ci-cd-guide|CI/CD guide]] instead. The policy is specified in CI.md.

Routine validation #

CI runs on pushes and pull requests targeting main/master, daily at 08:23 UTC, and through Actions → CI → Run workflow. Lint, all three Linux race/coverage shards, their aggregate Test (ubuntu-latest, 1.27) check, and macOS/Windows tests remain active. The CLI/search shard smoke-tests its existing binary with version and --help; there is no separate duplicate build.

Specialized checks use job-level changed-file filters on PRs and pushes:

Checks	Inputs
Font completeness and determinism	`scripts/generate_font_manifests.py`, `internal/fontcatalog/` (catalog, lock, manifests, licenses, font assets), `vendor/google-fonts/`
Rendering contract	`scripts/rendering-contract/`, `spec/rendering-contract/`, `pkg/renderingcontract/`, `pkg/palettes/`, `palettes/**`, `go.mod`, `go.sum`
Helm	`helm-chart/**`, including chart dependencies and chained test scripts
GoReleaser config	`.goreleaser.yml`, `go.mod`, `go.sum`

Changes under .github/workflows/** select every specialized check. Scheduled and manual CI runs execute all specialized checks regardless of paths. Docs-only PRs still receive ordinary checks rather than skipping the entire workflow and potentially leaving required checks pending.

The detection job uses dorny/paths-filter@v3: PRs use the changed-files API, including fork PRs, while pushes compare against the previous push commit. Only this job gets pull-requests: read, alongside contents: read. If detection fails, do not interpret skipped specialized jobs as validation. When adding a generator dependency, update its filter in ci.yml.

Spec conformance manifest #

When adding a normative requirement, assign it a stable DOMAIN-NNN ID in spec/conformance/requirements.yaml. Record its specification file, scope, conformance status, and the implementation and test files that support it. Mark incomplete or intentionally different behavior as partial and explain it in notes.

Run go test ./pkg/specconformance to check IDs, allowed values, referenced files, and the evidence required for implemented status. The normal CI test suite runs the same check. See the conformance manifest guide for the field definitions and rollout plan.

Build Lab observation #

The expensive TestBuildLab_LinkedAndFixtureMutationsCharacterizeProduct logs product failures as observations. PR CLI validation skips that test while retaining focused regression tests. Main push and daily/manual CI include it.

For a focused rerun, select Actions → Build Lab characterization → Run workflow and the desired ref. This separate workflow is manual-only because daily CI already runs the observation; a second daily run would duplicate work. It retains harness race detection, but no longer writes unused coverage data. Its success does not mean that every logged product observation passed.

Docker preview publishing #

Minimal and builder images publish automatically only on main pushes and v* tags. Relevant PR changes still build and validate both images without publishing. Tagged builds retain amd64/arm64 images and Trivy scanning.

To publish a feature preview explicitly, select Actions → Docker → Run workflow and choose the feature branch in Use workflow from. Both images publish to GHCR with branch and sha- tags; feature previews do not receive latest. Use the SHA tag when a stable preview reference is needed. Manual dispatch on main follows the existing default-branch tagging policy, and dispatch on a version tag follows the existing semver/multiarch policy.

Performance comparisons #

The initial benchmark sample selects only BenchmarkBuild_EndToEnd and BenchmarkBuild_Incremental. Concurrency keeps its separate three-sample run. Profiling and stage-specific sampling remain unchanged.

For a comparison, manually run Performance Benchmarks with compare_branch. The current checkout remains available for Go version/module setup; its benchmark measurements come from the downloaded current-results artifact. Only the comparison checkout generates a fixture and executes comparison benchmarks. Fixture or benchmark failures fail the job instead of being hidden as a successful comparison.

Scope #

Release tests, signing, SBOM generation, action versions, and repository settings are unchanged. Required-check or remote workflow registry changes are separate maintainer operations, not part of these repository workflows.

The bundled markata-go-site skill was reviewed (entrypoint, build/deployment, and faster-build guidance). No update is needed: these changes govern product maintainer CI, not site-author commands, build behavior, deployment workflows, or benchmarking guidance.

Golangci-lint v2 on Go 1.27 #

Go 1.27 uses golangci-lint v2.15.0, rather than the older v1.64.8 tool which cannot decode the Go 1.27 compiler export format. The migrated .golangci.yml retains all existing configured linters.

The new v2 analyzers also surfaced hundreds of historical findings in untouched files. To keep meaningful merge protection while progressively resolving that debt (tracked in issue #1902), PR and push CI now rejects new findings relative to the PR base or previous main commit. Scheduled CI runs the same new-issue gate plus a full-tree lint audit that reports failures without blocking the daily build. The full audit is deliberately visible, not suppressed.

For local work, run just lint after fetching origin/main to enforce new findings, or just lint-full to inspect all existing diagnostics. just lint-fast uses the supported v2 --fast-only mode. Once issue #1902 is resolved, restoring blocking full-tree lint is the exit criterion.

Build DAG plugin ownership inventory

2026-09-30T00:00:00Z

This document is the conservative ownership audit for the feature-flagged DAG executor. It follows the resource vocabulary in pkg/builddag: site, files, post, feed, cache, output, template, external, and plugin.

The inventory is intentionally stricter than an implementation-level code review. A plugin is not parallel-safe merely because its loop body looks independent. Unknown ownership, manager mutation, package/global caches, filesystem walks, external processes, and network access all keep work serialized until an explicit task boundary owns those resources.

Classification #

exclusive — site/global state or unclear ownership; keep serialized.
aggregate — reads or mutates a collection and therefore forms a barrier.
per-post candidate — plausible one-task-per-post boundary after an API refactor.
per-feed candidate — plausible one-task-per-feed boundary after an API refactor.
per-output candidate — plausible one-task-per-owned-output-path boundary after an API refactor.
external/network — external state, subprocesses, or network access requires a separate isolation/rate-limit policy even if item-local work exists.

All current LegacyTasks remain ScopeSite, Exclusive=true, and ParallelSafe=false. The classifications below describe possible future decomposition only.

Configure / discovery / load #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`build_cache`	exclusive	write `cache:*`, plugin state, lifecycle persistence	Keep barrier; expose namespace-safe cache operations before any overlap.
`theme_calendar`	exclusive	read/write `site:config`, plugin state	Configuration mutation must finish before downstream tasks.
`glob`	exclusive	write `files:*`, read `site:config`, filesystem walk	Discovery is a barrier that establishes the file set.
`background`	exclusive	read/write `site:config`	Configuration mutation must remain ordered.
`cdn_assets`	external/network + per-output candidate	network, cache, write `output:static/*`, config/plugin state	Separate fetch/cache planning from deterministic per-asset writes; add rate limits.
`icon_vendor`	external/network + per-output candidate	network/cache, vendor asset outputs, plugin index	Split vendor fetch/index from per-pack output ownership.
`tailwind`	external/network/exclusive	subprocess/toolchain, templates/includes, CSS output, config	Isolate subprocess inputs/outputs and eliminate shared include mutation.
`load`	aggregate/barrier	read `files:`, write `post:`, post index, cache	Load establishes the post collection; per-file parse tasks require deterministic merge/index phase.
`python_docs`	external + aggregate	source filesystem/import inspection, creates posts	Split source discovery/parse from deterministic post insertion.
`tag_aggregator`	aggregate	reads/writes all posts/tags and tag-derived state	Requires item-local normalization plus deterministic aggregate merge.

Transform #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`auto_title`	per-post candidate	write one `post:<id>`	Extract a post-local transform that does not iterate/mutate Manager collections.
`inline_titles`	per-post candidate	read/write one post title representation	Expose post-local transform.
`authors`	per-post candidate	read author config, write one post	Freeze author registry/config then expose post-local resolution.
`description`	per-post candidate	read/write one post	Expose post-local transform.
`structured_data`	per-post candidate	read/write one post metadata	Expose post-local transform with immutable site metadata input.
`reading_time`	per-post candidate	read content, write one post	Expose post-local calculation.
`stats`	aggregate	scans posts and writes shared statistics	Keep barrier or split item facts from aggregate reduction.
`breadcrumbs`	per-post candidate	read site/post routing state, write one post	Freeze route/index view then expose post-local generation.
`embeds`	per-post candidate + external/network	post mutation, cache/network for remote embeds	Split cached/local expansion from network resolution; explicit cache/external claims and rate limits.
`wikilinks`	aggregate/barrier	reads post index, writes post content/dependency edges	Freeze lookup index and collect dependency-edge deltas for deterministic merge.
`mentions`	per-post candidate	read blogroll/config, write one post	Freeze mention lookup state then expose post-local transform.
`hashtag_tags`	per-post candidate	read/write one post tags/content	Expose post-local transform after tag normalization barrier.
`webmentions_fetch`	external/network + per-post candidate	cache/network, attaches webmentions to posts	Separate fetch/cache refresh from post-local attachment.
`webmentions_leaderboard`	aggregate	scans webmention counts across posts	Keep barrier/reduction.
`toc`	per-post candidate	read/write one post	Expose post-local transform.
`jinja_md`	per-post candidate	read `template:*`, write one post	Make template environment read-only/thread-safe and expose post-local render.
`icons`	per-post candidate	read icon index/plugin state, write one post	Freeze icon index then expose post-local expansion.

Render #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`render_markdown`	per-post candidate	write one post rendered HTML, read renderer/plugin config	Expose a pure/post-local render operation with immutable renderer state.
`heading_anchors`	per-post candidate	read/write one post HTML	Expose post-local transform.
`image_zoom`	per-post candidate	read/write one post HTML	Expose post-local transform.
`webawesome`	per-post candidate	read/write one post HTML	Expose post-local transform.
`contribution_graph`	per-post candidate	read/write one post HTML	Expose post-local transform; isolate any shared renderer cache.
`md_video`	per-post candidate	read/write one post HTML	Expose post-local transform.
`youtube`	per-post candidate	read/write one post HTML	Expose post-local transform; keep network discovery out of task if introduced later.
`chartjs`	per-post candidate	read/write one post HTML	Expose post-local transform.
`csv_fence`	per-post candidate	read/write one post HTML	Expose post-local transform.
`mermaid`	per-post candidate + external	post HTML plus renderer/browser/cache depending on mode	Separate deterministic cache lookup from external rendering; explicit cache/external claims.
`glossary`	aggregate + per-post candidate	shared glossary/index plus post mutation; also writes glossary output	Freeze glossary dictionary before post-local linking; keep output generation separate.
`wikilink_hover`	aggregate + per-post candidate	reads post index/metadata, mutates one post	Freeze hover lookup snapshot then fan out post-local application.
`external_link_hover`	external/network + per-post candidate	network/cache and post HTML	Separate fetch/cache from deterministic application and rate-limit external tasks.
`link_collector`	per-post candidate	reads one rendered post, writes one post link metadata	Expose post-local collection; aggregate consumers wait on barrier.
`encryption`	per-post candidate	post content plus key/config state	Freeze immutable key/config inputs; ensure secrets never appear in graph diagnostics.
`link_avatars`	external/network + per-post candidate	favicon network/cache and post HTML	Separate fetch/cache refresh from deterministic post-local insertion.
`templates`	per-post candidate	read `template:*`, post/site metadata, write rendered page state	Make template environment immutable/thread-safe and expose one-post rendering API.

Collect #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`slug_conflicts`	aggregate/barrier	reads all post output routes	Keep validation barrier; could reduce per-post route facts first.
`series`	aggregate	reads posts, creates/mutates feeds/series metadata	Keep aggregate or split series-key grouping from deterministic feed creation.
`subscription_feeds`	aggregate	mutates shared feed collection	Keep feed-collection barrier.
`feeds`	aggregate	scans posts and constructs feeds	Keep aggregate until filtering/sorting can produce immutable feed plans.
`auto_feeds`	aggregate	scans tags/posts and creates feeds	Keep aggregate; deterministic feed-plan generation could precede per-feed work.
`blogroll`	external/network + aggregate	network/cache and shared blogroll/feed state	Separate external fetch plan/cache from deterministic aggregate merge.
`prevnext`	per-feed candidate	reads ordered feed posts, writes post navigation metadata	Build immutable feed ordering first; resolve conflicts for posts present in multiple feeds before fan-out.
`overwrite_check`	aggregate/barrier	reads all planned output paths	Keep validation barrier after output planning.
`static_file_conflicts`	aggregate/barrier	filesystem/static inventory + planned outputs	Keep validation barrier.

Write #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`static_assets`	per-output candidate	filesystem walk, writes `output:static/*`, asset hashes	Produce immutable copy plan then one task per destination namespace/path; serialize shared hash ledger merge.
`fontpack`	per-output candidate	reads config/assets, writes font/CSS namespace	Build immutable manifest then own disjoint output paths.
`palette_css`	per-output candidate	config -> known CSS output	Make generation pure and claim exact output path.
`aesthetic_css`	per-output candidate	config -> known CSS output	Make generation pure and claim exact output path.
`chroma_css`	per-output candidate	config -> known CSS output	Make generation pure and claim exact output path.
`css_bundle`	aggregate/per-output	reads multiple CSS outputs and writes bundle	Barrier on CSS producers; then own bundle path.
`publish_feeds`	per-feed candidate	reads one feed, writes feed-format paths	Generate immutable feed plan and one task per feed/format output.
`well_known`	per-output candidate	site metadata -> `.well-known/*`	Claim exact output namespace and remove shared writer state.
`publish_html`	per-post candidate + per-output candidate	reads one rendered post/template state, writes post output paths	Top candidate: expose one-post publish function and exact output claims; template state must be immutable.
`images`	aggregate	scans posts/assets and writes image inventory/pages	Keep aggregate until image records are planned; individual thumbnails/assets may fan out later.
`random_post`	aggregate/per-output	scans eligible posts, writes random endpoint/data	Keep eligibility reduction; output write itself can own fixed path.
`redirects`	per-output candidate	reads redirect declarations, writes redirect paths	Build/validate unique redirect plan, then one task per destination path.
`error_pages`	per-output candidate	templates/site config -> fixed error-page outputs	Freeze template state and claim exact paths.
`tags_listing`	aggregate/per-output	scans tag/feed state, writes tags page	Aggregate barrier, then fixed output task.
`feeds_listing`	aggregate/per-output	scans feed state, writes feeds page	Aggregate barrier, then fixed output task.
`garden_view`	aggregate	scans post graph, writes graph/page assets	Keep aggregate; later split graph reduction from fixed output writes.
`sitemap`	aggregate/per-output	scans published routes, writes sitemap outputs	Keep route reduction; fixed output task after plan.
`content_index`	aggregate/per-output	scans posts/feeds/source state, writes content index	Keep aggregate due cross-content contract.

Cleanup #

Plugin	Classification	Conservative resources / side effects	Refactor required before fan-out
`css_minify`	per-output candidate	filesystem walk/read/write CSS outputs	Build immutable file list first, then one task per CSS path; no shared mutable minifier state.
`js_minify`	per-output candidate	filesystem walk/read/write JS outputs	Build immutable file list first, then one task per JS path.
`css_purge`	aggregate/external	scans generated HTML/CSS and rewrites CSS	Keep barrier until usage analysis can be separated from per-file rewrite.
`pagefind`	external/exclusive	subprocess scans final output and writes search index	Keep serialized external barrier with explicit output namespace.
`diagnostics_artifact`	exclusive	reads final lifecycle diagnostics/executor state, writes `.markata/diagnostics.json`	Must remain final publication barrier; never overlap unfinished build work.

First fan-out candidates #

The first fan-out PRs should stay serial even after the graph contains item-level nodes. Resource claims should be added before any task is marked parallel-safe.

publish_html — one task per post/output path. High payoff and naturally disjoint output ownership. Refactor the plugin to produce an immutable publish plan, then expose a one-post writer. Claims: read post:<id> and template:*; write output:<post-path>.
publish_feeds — one task per feed/format. Feed objects already form natural units and outputs are usually disjoint. Claims: read feed:<slug>; write exact output:<feed-path>.
render_markdown — one task per post. CPU-heavy and item-local in intent. First make renderer/config state immutable and extract a post-local API. Claims: write post:<id> plus read-only plugin/config resources.
reading_time — one task per post. Small, low-risk proving ground for the per-post task API and graph fan-out mechanics. Claims: write post:<id>.
css_minify / js_minify — one task per planned output file. Straightforward filesystem ownership once directory walking is separated into a deterministic planning barrier. Claims: write exact output:<path>.

auto_title, description, toc, heading_anchors, image_zoom, and several HTML transforms are also strong per-post candidates, but they should follow the first shared per-post adapter rather than each inventing a scheduler integration.

Required safety rules before concurrency #

A fan-out task must name every mutable/shared resource it reads or writes.
Unknown ownership remains exclusive.
A write claim owns reads performed as part of mutating the same resource; a task must not declare duplicate read+write claims for one resource.
Collection planning/validation remains a barrier before item-level tasks consume the plan.
External/network work needs explicit cache ownership, cancellation, and a bounded rate/concurrency policy separate from CPU/file task concurrency.
Output tasks claim normalized destination paths/namespaces; overlap checks happen before scheduling.
Package/global template/browser/plugin caches must be proven read-only or made task-safe before post-level concurrency.
Build Lab differential/incremental/determinism checks and race tests remain mandatory gates for each fan-out slice.

Next implementation sequence #

Land deterministic resource claims (#1452).
Add compiled graph/resource diagnostics (#1454) so ownership is inspectable.
Introduce a serial item-task adapter and use reading_time as the smallest per-post proof.
Move render_markdown to serial per-post tasks and verify Build Lab equivalence.
Add immutable publish planning, then split publish_html and publish_feeds into serial per-output tasks.
Only after the graph and diagnostics prove disjoint ownership should any task become ParallelSafe=true or the executor accept MaxParallel > 1.

Compiled graph core contract #

The core specification defines the snapshot and diagnostic guarantees supporting this inventory (#1451, #1454):

Compile snapshots artifact/resource slices and external inputs. After compilation, callers may reuse or mutate declaration arrays without changing the compiled graph. Graph.Task returns independent metadata slices, retaining the distinction between nil and empty slices. Task functions still own the mutable state captured by their closures; snapshotting declarations does not make plugin state immutable or parallel-safe.
Artifact identity and canonical ordering use (Kind, Key), not String(). For example, post / rendered:example and post:rendered / example are distinct artifacts even though their display strings match. Resource reports sort by (Resource.Kind, Resource.Key, Access). Keep keys opaque; do not parse display strings to recover ownership.
The compiler chooses the lexicographically smallest currently ready task, using reverse adjacency and a min-heap rather than rescanning every task. Fan-out/fan-in does not change this serial order or stable cycle diagnostics.
Empty ownership remains valid for conservative compatibility tasks. Reports explicitly show empty claims as []; serialization omits empty optional fields. Scope is descriptive and does not infer dependencies or claims.
Structural digests identify declarations only. They do not prove that content or external state is unchanged and must not be used to skip execution.

These guarantees harden graph inspection and compilation, not concurrency: MaxParallel remains one, existing scheduling defaults remain unchanged, and task failures and cancellation continue to surface as errors.

Experimental DAG builds

2026-09-29T00:00:00Z

markata-go build --dag --benchmark-json=dag.json
markata-go build --dag=false --benchmark-json=legacy.json

--dag selects an experimental task-graph executor. The normal lifecycle executor remains the default. Both retain the same plugin order, lifecycle stages, output formats, and cache behavior. The DAG executor runs one graph task at a time; existing plugins may still use their own internal worker pools. It is not a switch for additional parallelism or a guarantee of faster builds.

The DAG executor takes one snapshot of the plugins scheduled for each stage. It builds each plugin’s graph when that plugin is reached, after earlier plugins have finished. A plugin added during a stage can run in a later stage, but does not join the stage already in progress. This preserves the normal lifecycle’s plugin ordering while allowing later graphs to use the current post and feed state.

The flag is also available on serve and builder-admin. Builder Admin passes the choice to queued build processes. Use MARKATA_GO_DAG=true for an environment-wide opt-in, and --dag=false to override it for one command. An invalid environment boolean produces a clear error unless an explicit flag overrides it.

build --dry-run keeps its existing partial lifecycle through Collect. It does not execute the DAG scheduler or publish the full-build diagnostics artifact. Full-build benchmark JSON and <output>/.markata/diagnostics.json identify the executor that actually ran.

Compare builds fairly #

Run a cold build, one warm-up build, and at least three warm samples per executor. Alternate the order of the warm samples. Use the same source, configuration, worker count, output-processing flags, and external cache snapshot. Report cold and warm measurements separately.

Keep encryption settings identical for both executors. If local measurements disable encryption because keys are unavailable, do so only in isolated local copies, state that limitation, and do not deploy those outputs. Disable external index ingestion or other publication side effects for local benchmarks.

Live network responses can change embeds, favicons, and feed content between builds. Reuse a populated external cache for scheduler comparisons rather than interpreting remote variability as a DAG difference. Compare generated output bytes as well as timings; diagnostics timestamps, executor identity, and .well-known/time intentionally differ.

The verbose plan= digest describes the graph’s declarations. It is not a content fingerprint, proof that inputs are unchanged, or permission to skip tasks. Graph compilation snapshots metadata and uses canonical ordering, but task functions still own their runtime inputs and mutations.

For development iteration, use [[cli-reference|CLI Reference]] and the existing --fast or serve --incremental options rather than assuming --dag skips output work.

Calendar Feed Views

2026-09-28T00:00:00Z

Every normal Markata-Go HTML feed includes a Calendar view by default. You do not need a second feed, a template override, or special calendar configuration.

The interaction is inspired by Jim Nielsen’s calendar archive: the normal archive and its calendar are peer views of the same collection, and dates with posts are visibly marked. Select a marked date to reveal the title or titles published that day.

Open Calendar #

Open any feed normally and choose Calendar from its view control. For a feed at /blog/, the same state can be linked directly as:

/blog/?view=calendar

For the root feed, use:

/?view=calendar

The Simple view also links to Calendar. When feed sidebars are enabled on posts, the sidebar includes a calendar link for the currently selected feed.

What the view shows #

Calendar uses the feed’s complete feed.posts collection, so it represents the full feed even when the normal HTML presentation is paginated.

For each represented year it renders all twelve months. Every day appears in the correct weekday column. Dates containing posts get an activity marker and an expandable list of titles. If multiple posts share a date, they all appear beneath that day.

Posts without a valid date cannot be placed in a month grid. They remain available through the normal feed presentation.

Three human-facing views #

A default feed now has three presentations:

Posts — the feed’s normal card/list/template presentation
Simple — the existing compact HTML list at /simple/, when enabled
Calendar — the publishing-rhythm view, opened in place and deep-linkable with ?view=calendar

RSS, Atom, JSON, Markdown, and text remain feed export/subscription formats rather than presentation modes.

Built-in alternate HTML layouts such as feed-photo-grid.html keep their existing primary presentation and gain Calendar as a peer view too.

Accessibility and progressive enhancement #

The normal feed remains the server-rendered default. Calendar controls stay hidden until JavaScript successfully initializes, so visitors without JavaScript keep the existing feed experience.

The page embeds a hidden dated source built from the complete feed collection. Calendar day disclosures use native <details> and <summary> controls, so marked dates are keyboard-operable without a custom keybinding layer. Weekday labels and day summaries expose useful accessible names while decorative activity marks stay hidden from assistive technology.

Pagination #

You do not need to disable pagination. The visible Posts view may render page.posts, while Calendar intentionally reads the complete feed.posts collection.

Customizing Calendar #

Calendar styling and behavior live in the default theme assets:

css/calendar-feed.css
js/calendar-feed.js

The CSS uses theme variables and currentColor-derived borders/backgrounds so it follows custom palettes without calendar-specific color configuration.

The previously shipped calendar-feed.html remains available for sites that intentionally want a dedicated calendar-first custom template. It is no longer required to enable Calendar on ordinary feeds.

Pins

2026-09-27T00:00:00Z

Markata includes a built-in /pins/ page for saved links. Published posts appear there when they have a non-empty link or url field. Items appear newest first.

---
title: "A field guide to useful maps"
link: "https://example.com/field-guide"
description: "A thoughtful guide to reading a landscape."
image: "/images/maps.webp"
date: 2026-09-27
published: true
---

A note about why this is worth saving.

Link posts can also use url for their destination.

The pinboard keeps the title linked to your local post and provides a separate source link to the external URL. Images, descriptions, dates, tags, and authored notes remain ordinary post data.

The default board uses the available viewport width, with responsive masonry columns and 100 pins per page. The header has extra breathing room; card footers share the card background. Hovering subtly emphasizes cover art without moving cards or opening floating notes.

Cover art and notes #

Pins uses image, cover, cover_image, or og_image, in that order. When those fields are empty, it reuses image previews from already-rendered embeds, YouTube embed thumbnails, or images in the post body. The pins page itself does not fetch metadata for arbitrary posts. Link-style posts automatically generate a preview from their link or url frontmatter destination. For other posts, use the normal embed syntax to supply an external preview:

![[https://example.com/field-guide]]

I saved this for its clear examples and detailed maps.

Your commentary appears below the title as a short note. Click or tap Note, or activate it with the keyboard, to expand the text inside the card. Embedded destination descriptions and standalone source URLs are excluded from the note. If there are no authored paragraphs or list items, a non-URL description is used instead. Both cover art and notes work without JavaScript.

Customize pagination #

Define a Pins feed to use a different page size or pagination mode:

[[markata-go.feeds]]
slug = "pins"
title = "Pins"
filter = "published == true and (link or url)"
sort = "date"
reverse = true
items_per_page = 50
pagination_type = "manual"

[markata-go.feeds.templates]
html = "pins.html"

[markata-go.feeds.formats]
html = true

See feeds for pagination and format options, and templates for overriding the board design.

The link field is intentionally render-neutral outside the pinboard. Adding link: does not inject an external preview into the individual post and does not cause an external metadata request by itself. Existing sites can therefore keep using link as ordinary frontmatter without changing post rendering.

Route ownership #

The built-in Pins feed is a convenience route, not a reservation. If your site already has a publishable post with the slug pins, that post keeps /pins/ and Markata does not inject the implicit feed. A draft, skipped, or unpublished pins post does not reserve the route.

An explicitly configured feed with the slug pins also takes precedence over the built-in definition.

Default behavior #

The implicit Pins feed uses:

filter: published == true and (link or url)
sort: date
reverse: true
items_per_page: 100
pagination_type: manual
format: HTML
path: /pins/
template: pins.html

Disabling built-in subscription feeds disables the implicit Pins feed along with the implicit root and archive feeds. You can still define your own pins feed when you want different selection, sorting, pagination, templates, or output formats.

Nginx-native redirects

2026-09-27T00:00:00Z

The built-in redirects plugin generates nginx-native redirect rules from the same static/_redirects file used for static HTML fallbacks.

Default behavior #

Given:

/old-post /new-post
/go/docs https://docs.example.com/start

A normal build writes under the configured output_dir:

<output_dir>/
├── redirects.conf
├── old-post/index.html
└── go/docs/index.html

redirects.conf contains exact-match nginx rules:

location = "/old-post" {
    return 301 "/new-post";
}

location = "/go/docs" {
    return 301 "https://docs.example.com/start";
}

HTML fallback pages remain enabled by default so the same build artifact continues to work on static hosts that do not consume nginx configuration.

Configuration #

[markata-go.redirects]
redirects_file = "static/_redirects"
redirect_template = "templates/redirect.html" # optional
html_fallback = true

Set html_fallback = false when the deployment is guaranteed to use the generated nginx rules and you do not want new per-path HTML redirect pages:

[markata-go.redirects]
html_fallback = false

When changing this setting on an existing incremental output directory, use a clean build if you also want old HTML fallback files removed. Markata-go deliberately does not delete arbitrary index.html files because redirect paths can overlap normal site content and custom templates do not provide a safe ownership marker.

Keeping `redirects.conf` current #

On normal builds, nginx output is refreshed whenever the configured _redirects file exists. If that file is empty, markata-go writes a valid header-only redirects.conf, so previously generated native rules cannot remain active.

If the _redirects source is deleted, markata-go removes an existing redirects.conf only when it recognizes the file as its own generated artifact. A user-managed redirects.conf is left untouched.

When _redirects exists, redirects.conf is the plugin’s generated output path. If the output directory already contains a file at that path that is not marked as Markata-generated—for example static/redirects.conf copied by the static-assets plugin—the build fails with a clear conflict instead of overwriting it. Rename or remove the manually managed file before enabling generated nginx redirects.

Include from nginx #

Include the generated file from inside the nginx server block that serves the built site:

server {
    listen 80;
    server_name example.com;
    root /usr/share/nginx/html;

    include /usr/share/nginx/html/redirects.conf;

    location / {
        try_files $uri $uri/ /index.html =404;
    }
}

The include path must match the deployed output_dir.

Release directories and `current` symlinks #

If a deployment serves releases through a current symlink, point the include at the active release only when the nginx process will be reloaded as part of the release switch. Nginx reads included configuration when it loads or reloads its configuration; changing the symlink alone does not make an already-running nginx process reread redirects.conf.

For builder-admin or other in-place release switching, either:

reload nginx after activating a release whose redirect config changed, or
keep nginx-native redirects out of that live-switch path until a reload hook is part of the deployment.

HTML fallbacks continue to work without an nginx reload because they are served as ordinary files from the active release.

Supported rules #

The native output intentionally follows the redirects plugin’s existing parser:

source paths must start with /
destinations must be /absolute-path, http://..., or https://...
comments and blank lines are ignored
malformed rules are ignored
wildcard rules containing * are skipped
extra fields such as platform-specific status codes are currently ignored
generated nginx redirects use HTTP 301

This keeps nginx output and HTML fallback behavior aligned. Use hand-written nginx configuration or the hosting provider’s native redirect system for wildcard, conditional, or status-code-specific rules.

Fast builds #

The redirects plugin is skipped in --fast mode. Run a normal build before publishing, validating, or reloading nginx with redirects.conf.

Markdown Containers

2026-09-27T00:00:00Z

markata-go supports fenced Markdown containers for grouping content in a <div> with classes, an optional ID, and custom attributes.

Basic container #

Use three or more colons followed by a class name or attributes to open a container. Close it with a bare line containing only the same number of colons.

::: card {#intro .featured data-kind="note"}
This Markdown is inside the card.

:::

The closing line must be colon-only. A line such as ::: card, ::: {.card}, or a decorated/indented marker should not be used as a closer.

Nested containers #

Use a longer fence for each nested level and close each level with its matching bare fence. This makes the structure predictable and keeps content after an inner close inside its parent container.

::: cards
Outer content before the card.

:::: card
Inner card content.

::::

Outer content after the card.

:::

The example above renders the card inside cards, then continues rendering the final paragraph inside the outer cards container.

A useful rule is:

Purpose	Example
Open outer container	`::: cards`
Open nested container	`:::: card`
Close nested container	`::::`
Close outer container	`:::`

Do not rely on a shorter outer closing fence to implicitly close deeper nested containers. Close the innermost container first with the same number of colons it used to open, then close the parent.

Classes and attributes #

The opening line can include multiple classes and an attribute block:

:::: panel wide {#example .accent data-state="ready"}
Content

::::

This produces a container with the classes panel, wide, and accent, the ID example, and the custom data-state attribute.

Native tabs (no Web Awesome required) #

Native tabs use the same fenced-container syntax as md-card. Every panel is rendered to HTML on the server. Without JavaScript, all panels remain visible with headings; when JavaScript loads, a small keyboard-accessible tab strip replaces the headings. Printing expands all panels.

::: md-tabs {data-label="Installation methods" style="boxed"}

:::: md-tab {label="curl"}
```bash
curl -fsSL https://example.com/install.sh | bash
```
::::

:::: md-tab {label="mise"}
```bash
mise use -g github:WaylonWalker/markata
```
::::

:::

The outer md-tabs uses three colons, with direct child md-tab containers using four. Tabs may contain ordinary Markdown, code fences, cards, and nested blocks. Use style="boxed" (default), style="underline", or style="pills"; data-style is also accepted. Use data-label to give the tab group an accessible name. Tab labels are plain text. On narrow screens the tab strip scrolls horizontally. Native tabs have no Web Awesome dependency and the enhancement script only loads on pages using them. Existing wa-tabs continue to work separately.

Web Awesome example #

The same nesting rule is useful for components that transform Markdown containers after rendering:

::: wa-tabs

:::: wa-tab {label="macOS"}
```bash
brew install markata-go
```

::::

:::: wa-tab {label="Linux"}
```bash
curl -fsSL https://example.com/install.sh | sh
```

::::


:::

The outer wa-tabs container uses three colons and each nested wa-tab uses four, so the structure is unambiguous.

Roads #

The default theme turns a road container into a scroll-drawn path of linked milestones:

::: road timeline

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

:::

See Roads for all styles and options.

For prose-led histories, use ::: road editorial story with a heading per entry. A leading :lucide-name: becomes a rail badge; an emphasis-only paragraph directly after the heading becomes its eyebrow label. Add reveal (::: road editorial story reveal) for optional, reduced-motion-safe scroll entrances. story alone opts into larger type and diamond-bullet highlights; plain editorial roads keep their existing typography.

Responsive article layouts (static HTML and CSS) #

Markata also provides opt-in, article-scoped layout classes built from the same fenced containers. They generate plain HTML at build time: no JavaScript, external assets, or custom component framework. These classes intentionally use md- prefixes to avoid changing existing ::: card, ::: columns, !!! vsplit, and feed cards.

Container	Result
`md-layout`	Bordered grouping for an architecture diagram
`md-box`	Simple bounded box
`md-card`	Soft-surface card (scrollable if it contains a wide table)
`md-columns`	Auto-fitting equal-width columns, stacking when narrow
`md-grid`	Responsive grid, with optional fixed column count
`md-stack`	Vertical grouping
`md-divider`	Subtle rule
`md-connector`	Decorative arrow between rows
`md-section`	Section with automatic heading/intro column, sticky on wide screens

Use {data-gap="sm"} or {data-gap="lg"} on grid/stack/layout containers, {data-columns="2"} (also 3 or 4) for explicit desktop columns, and {data-align="center"} on a card or box. Explicit columns stack at narrow viewports. Unknown values retain the defaults; arbitrary CSS is not accepted. Use descriptive text to convey relationships, rather than relying on arrow direction alone for accessibility.

Heading permalink links stay inline inside md-card, including nested headings, so ordinary titles do not add a horizontal scrollbar. The links remain available on hover and keyboard focus. Wide code blocks still scroll independently; a wide comparison table can scroll within its card without widening the page.

Markdown story pages #

Set content_width: wide in a post’s frontmatter to opt into a wider frame, larger balanced title, and a larger opening paragraph. Other pages keep their existing appearance. This option applies to the default post.html template (custom templates must opt in themselves).

Start each md-section with an H2. The heading and the paragraph immediately after it become the section head; everything else becomes the body. At 1100px and wider the head sticks beside the body while scrolling. Smaller screens stack them; print uses static headings. Without a leading H2, all content stays in the body.

---
title: "From foundations to agent workflows"
content_width: wide
---

A short opening paragraph introduces the story.

::: md-section
## 2026 · Agent workflows and access

Agents became first-class platform users.

### Identity and access

Longer narrative, lists, tables, and cards go here.
:::

A short token (up to 16 characters, no spaces) followed by the exact separator · becomes a large primary-color kicker. The full heading’s ID is unchanged: the example still links to #2026-agent-workflows-and-access. No JavaScript or separate story-head container is needed.

For a timeline overview, add the rail modifier to an md-grid:

::: md-grid rail {data-columns="2"}
:::: md-card
::::: md-icon
:lucide-bot:
:::::

_2026_

### [Agent workflows](#2026-agent-workflows-and-access)

Agents inspect runs and read logs.

::::

:::: md-card
_2025_

### [Platform visibility](#2025-platform-visibility)

Telemetry reaches more teams.

::::

:::

At 1000px and wider, a rail joins card tops with ring ticks that fill on hover or keyboard focus. The default is four columns; data-columns="2", "3" or "4" overrides it. Below 1000px cards stack along a vertical rail with ring ticks. The ticks remain visible and fill on hover or keyboard focus. A card’s heading link stretches over the card; keyboard focus outlines the card. Use one heading link per card and avoid other interactive controls in these overview cards. An emphasis-only paragraph supplies the small uppercase monospace kicker. Rail cards allow visible overflow so the ring ticks remain visible above their tops. An md-section immediately after the rail gets responsive spacing from 4.5rem to 7.5rem. These defaults need no page-local CSS.

For unresolved items, use ::: md-grid pending with nested md-card containers. Cards get dashed borders, transparent backgrounds and muted icons. Both variants use ordinary Markdown, work without JavaScript, and retain theme colors. See rendering-fixtures/story-layout.md for a full example.

Architecture diagram #

::: md-layout

:::: md-box {data-align="center"}
### Falcon3 — Kubernetes
Two deployments, shared published site volume.


::::

:::: md-columns {data-gap="sm"}

::::: md-card {data-align="center"}
### Website
Nginx serves current release.


:::::

::::: md-card {data-align="center"}
### Builder Admin
Builds and publishes releases.


:::::



::::

:::: md-connector {data-direction="both"}


::::

:::: md-box {data-align="center"}
### Shared `/data/site` Longhorn PVC
Replicated storage: NVMe + HDD.


::::



:::

The connector arrows are only a decorative aid, not a replacement for the descriptive labels. For connected arbitrary graphs, use Mermaid.

Icons and feature rows #

The built-in icons plugin already accepts Lucide shortcodes like :lucide-rocket:. Combine those shortcodes with md-icon (centered icon, optional {data-size="lg"}), or with an md-feature row containing a md-feature-icon and md-feature-body. No new icon font, CDN, or JavaScript is necessary.

::: md-feature

:::: md-feature-icon
:lucide-rocket:

::::

:::: md-feature-body
### Verify production
Smoke-test the new Markdown components at mobile widths.

::::

:::

The icon remains decorative, so provide readable heading text. The row stays within its article column at narrow widths. For side-by-side icon cards or more icon names, see Icon Shortcodes.

Side-by-side tables #

::: md-columns

:::: md-card
### Current storage

| Node | Capacity |
| --- | ---: |
| Falcon2 | 3 TB |
| Falcon3 | 4 TB |


::::

:::: md-card
### Proposed storage

| Node | Capacity |
| --- | ---: |
| Falcon2 | 3 TB |
| Falcon3 | 14 TB |


::::



:::

Each table remains normal semantic Markdown HTML and can independently use table sorting when enabled. Cards keep their own horizontal overflow instead of forcing the whole article to scroll. For more examples, see examples/gallery-site/pages/layout-primitives.md.

Status and metric reports #

You can also compose native, accessible status badges, metric cards, progress bars, and before/after comparisons. See the Markdown metrics guide for the required values, labels, and data-tone options.

Serve Control Center design

2026-09-26T00:00:00Z

Existing Builder Admin #

The markata-go builder-admin command launches pkg/builderadmin.Service from the same executable as the normal CLI. Helm launches this command in the builder image. The service has a leader-locked, serialized queue for builds, refresh tasks, and rollback. It keeps queued and running operations, completed build and refresh records, trigger identity, timestamps, changed paths, release metadata, and log file paths. It persists state.json and per-job text logs under its history directory. The UI polls /api/state; users can enqueue a build or refresh, inspect logs, and promote a retained release. Build jobs execute a child markata-go build process before release promotion. Proxy identity, HTTPS origin validation, and CSRF protect the production UI.

Builder Admin does not currently hold page status, warnings, structured diagnostics, step records, or structured log events. Its local command binds to loopback by default, but the protected UI cannot be used without the proxy contract. The existing release and queue workflow stays in place. The local serve control view is mounted on the serve listener and consumes the shared session runtime. This avoids weakening production authentication.

Shared state #

A session runtime stores jobs, steps, logs, diagnostics, pages, and server status. It sends immutable snapshots to subscribers. Build integration creates an initial job and a job for each rebuild, with one step per lifecycle stage. The existing content diagnostics ledger supplies page dispositions and stable codes. Errors that stop a build early create session diagnostics. Text logs are retained within a bounded buffer, while job and diagnostic history remains accessible after a successful rebuild.

The terminal and local web clients render runtime snapshots. They keep only their own view state, such as selection, search, and scroll position. Actions return to the runtime and use one validated handler. Build state never comes from parsing displayed log text.

Operational behavior #

The serve listener reports ready only after binding. Interactive terminals use Bubble Tea. Redirected and CI output stays line-oriented, and --no-tui forces it. The local web view is /_markata/ on the serve listener when --admin is set; markata-go admin starts the same serve runtime with that view enabled. Its default host is loopback. Fatal errors remain visible after the TUI exits. Shutdown closes the server, watcher, and subscribers.

Validation #

Unit tests cover runtime lifecycle, history, diagnostic attachment, subscriber behavior, and actions. Client tests render synthetic snapshots at normal and narrow widths and exercise navigation, resize, search, and log scrollback. Command tests cover TTY selection and local web launch. Manual terminal and browser checks verify the integrated path.

Gallery pages and title sizing

2026-09-26T00:00:00Z

Issue: #1289

Design #

The default theme will provide gallery.html for a post whose gallery frontmatter is a list of images. Each item has a required src and alt, with optional caption, width, and height. The template renders an ordinary linked image gallery. CSS creates a responsive masonry layout; a small script upgrades links to a dialog with keyboard and touch navigation. Full image links remain useful without JavaScript. The theme asset helpers make the CSS and script available to projects without copied assets.

The existing feed-photo-grid.html already supports shots. Its cards will gain the word count used by Rhiannon’s site for longer entries and load priority will favor only the first visible row. Site-specific colors and typography stay in site CSS.

Post titles will receive a build-time length category derived from the plain title. CSS uses it as a conservative initial size and preserves wrapping. An optional browser fit pass can refine the size against the byline after fonts load and on resize. This keeps the first paint readable and avoids assuming the build knows the final font metrics or viewport.

Verification #

Render a demo gallery and a shots feed from local fixture content, inspect the generated HTML, test the gallery viewer and long title in a browser, and run relevant Go tests. Include screenshots in the pull request when capture is available.

Serve Control Center

2026-09-26T00:00:00Z

Start a local development session:

markata-go serve

In a terminal, serve opens a dashboard showing server status, recent jobs, warnings, errors, pages, and logs. The site remains at http://localhost:8000. File changes create rebuild jobs. Each job keeps its steps and diagnostics, so a failed rebuild remains inspectable after the next successful one.

For line-oriented output, use markata-go serve --no-tui. Markata also chooses line-oriented output when input or output is redirected, when --no-input is set, or when the terminal is unavailable. This mode works in scripts and CI. While the interactive dashboard is open, build and plugin messages appear in its Logs and Problems views. Serve keeps terminal ownership so rebuild output does not overwrite the dashboard, including while the terminal is resized.

Local web dashboard #

markata-go serve --admin
# Site:  http://localhost:8000/
# Admin: http://localhost:8000/_markata/

markata-go serve enables this dashboard by default on a loopback listener. markata-go serve --admin remains supported. Use --no-admin to disable the dashboard. A non-loopback bind, such as --bind 0.0.0.0, leaves it disabled; requesting --admin on such a bind fails. The dashboard URL appears in plain startup output and as an Admin shortcut in the TUI.

markata-go admin starts the same local serve session with the web dashboard and line-oriented terminal output. Both commands show the same jobs, warnings, errors, and pages that the terminal dashboard sees. The local admin dashboard only binds to loopback. For remote, release-oriented operations use the protected Builder Admin deployment guide.

The web dashboard supports manual builds, job reruns, and rebuilding a selected page. Jobs keep logs and lifecycle steps. Page details show source diagnostics and suggested fixes when Markata has enough context. You can open a generated page from its page entry when it has a URL. The Feeds section uses the same feed and post metadata as the build, and its post links open the matching page details.

The browser URL records the current section, selected item, and filter in its fragment. You can copy a link to a job, problem, page, feed, or filtered log view. Browser Back and Forward restore earlier selections and sections.

Key	Action
`j` / `k`, arrows	Move through the current list
`Enter`	Move focus to the selected item’s details
`Esc`	Clear the current selection or close keyboard help
`/`	Focus the current section’s filter
`g` / `G`	Select the first or last item
`w` / `e`	Show warnings or errors
`p` / `f` / `l`	Open pages, feeds, or logs
`r`	Rerun the selected completed job while Jobs is active
`?`	Show keyboard help

Shortcuts pause while a text field or editable element has focus. At narrow window widths, the list and details use a single-column layout with a fixed section bar. Focus indicators remain visible for keyboard use.

The browser colors follow the configured Markata palette through semantic roles for surfaces, text, links, focus, status, code, and buttons. The shared semantic token stylesheet is also used by Builder Admin, which keeps its separate production workflows and page structure. A shared browser shell is tracked in #1300; the local fix preview and source mutation actions remain available only in local Serve.

Review and apply fixes #

The local Problems view can preview source fixes before applying them. Plans show their category, safety class, source location, and before/after text. Use Review all safe to review every currently safe fix, a category button to review one group, or Select on individual problems followed by Review selected. The review dialog lists every proposed edit before you approve the batch. It shows a full-file diff for each source file using bundled assets, so review works without internet access. If rich rendering fails, the dialog shows a text diff of the same previewed edits. SAFE fixes are deterministic edits that can be selected together; REVIEW fixes need closer inspection; MANUAL diagnostics provide guidance without an automatic edit. Markata never applies a fix until you review a preview and choose to apply it. The server authorizes only the exact files, digests, and selections in that preview, and consumes that authorization after one apply attempt. The retired single-file preview/apply endpoints are not exposed; all source mutation uses the grouped batch preview/apply contract.

Each source file is checked against the digest captured by the preview. If the file changes before apply, Markata skips that file and reports it. In a mixed batch, still-valid files may be applied while stale files remain untouched. Markata requests one rebuild after applying any fixes. The build job then refreshes the current diagnostics projection. The apply response means the rebuild was queued; the Problems view updates when that job completes. Ambiguous dates and duplicate frontmatter keys do not receive automatic safe edits.

Terminal controls #

Key	Action
`j` / `k`, arrows	Move selection or scroll
`Enter`	Inspect selected job, page, or diagnostic
`Esc`	Return to the previous view
`t`	Trigger a build
`r`	Rerun the selected job
`w` / `e`	Open warnings or errors
`l`	Open logs
`p` / `f`	Open pages or feeds
`o` / `v`	Open selected source or local preview
`a`	Open Admin in the browser when available
`/`	Search or filter the current view
`g` / `G`	Jump to first or last item
`PgUp` / `PgDn`	Scroll by a page
`?`	Show help
`q`	Quit

When you scroll away from the live log tail, new lines do not move your view. The dashboard shows a count of new lines until you return to the bottom. Resize the terminal at any time; narrow windows use a single-column layout.

Reading diagnostics #

A diagnostic has a stable code, source path and line when known, the job that found it, and a suggested fix. The warnings and errors inboxes retain entries for the session history. The Problems view uses current diagnostics from the latest page inventory, newest completed job, and any running job; a successful rebuild removes resolved findings from that view. Their original job records remain available. Selecting a page shows its current status and diagnostics; selecting a job shows the diagnostics from that run. Some plugin messages do not include a source location. Those remain in the job and session inbox so they cannot disappear into log scrollback.

Photo Galleries

2026-09-26T00:00:00Z

Create a gallery page with template: gallery.html and a list of images:

---
title: "Field Notes"
description: "Photographs from the garden."
date: 2026-09-26
published: true
slug: gallery
template: gallery.html
gallery:
  - src: /images/flowers.webp
    alt: Pink flowers in afternoon light
    caption: Late summer in the garden
    width: 1600
    height: 1067
  - src: /images/leaves.webp
    alt: Rain on broad green leaves
    width: 1200
    height: 1800
---

An optional introduction can follow the frontmatter.

Each image needs src and meaningful alt text. caption is optional; when present, it appears below the thumbnail and in the full-screen viewer. Add the original image’s width and height when you know them so the page reserves space while loading. Images without both fields still render. The page uses two columns on small screens, three on medium screens, and four on wide screens. Readers can open an image, use the centered icon buttons or arrow keys to move through the gallery, swipe horizontally on touch screens, and press Escape to close it. Image changes slide into view; the motion respects the device’s reduced-motion preference. The original image links work without JavaScript.

Relative image paths and trusted media hosts receive an 800-pixel-wide preview. Other image URLs are used as supplied. See template media settings if your images live on another CDN.

Photo-first feeds #

Use the existing photo grid template for a feed of individual photo posts:

[[markata-go.feeds]]
slug = "shots"
title = "Shots"
filter = "published == true and 'shots' in tags"
sort = "date"
reverse = true
views = ["default", "simple", "calendar", "shorts"]
shorts_path = "/shorts/"

[markata-go.feeds.templates]
html = "feed-photo-grid.html"

Set each post’s image or cover_image, plus a title and description. Add card_classes: "col-span-2" to let a selected card span two columns. The grid shows a date and, for longer posts, a word count when those values are available. With the opt-in Shorts view, /shorts/ presents every item in the same filtered and sorted feed as a full-screen image/video viewer. Swipe vertically, scroll, or use keyboard arrows; the URL hash tracks the stable post ID and can be shared. See feeds for filtering and pagination.

Long post titles #

Post pages now get a conservative starting size based on title length. The browser refines the fit after the active font loads and when the viewport changes. Titles remain visible and may wrap when the space beside the byline is narrow. This works with custom font packs and does not require site JavaScript.

Image Library

2026-09-13T00:00:00Z

markata-go can generate an image inventory and a page for finding images used by your site. The default output is:

/images/ — a responsive, searchable image library
/images/index.json — a versioned machine-readable inventory
/images.json — the same inventory at the site root for other tools

The plugin runs by default. It reads public posts and, when include_unreferenced is enabled, the configured static asset directory. It does not fetch remote images or videos.

Configure the output #

Add an images table under [markata-go] when you need to change the defaults:

[markata-go.images]
enabled = true
path = "images"
template = "images.html"
export_json = true
include_unreferenced = false

Option	Default	Description
`enabled`	`true`	Generate the image library page and inventory.
`path`	`"images"`	Relative output directory below `output_dir`.
`template`	`"images.html"`	Template used for the HTML page.
`export_json`	`true`	Write `path/index.json` and `/images.json`.
`include_unreferenced`	`false`	Include image and video files found in `assets_dir` even when no public post uses them. Set `true` explicitly for a local authoring inventory because it makes all supported asset files enumerable.

The output path must stay inside output_dir. The same options work in YAML and JSON configuration files. Environment overrides use these names:

MARKATA_GO_IMAGES_ENABLED
MARKATA_GO_IMAGES_PATH
MARKATA_GO_IMAGES_TEMPLATE
MARKATA_GO_IMAGES_EXPORT_JSON
MARKATA_GO_IMAGES_INCLUDE_UNREFERENCED

Find and copy an image #

The library searches image filenames, paths, alt text, figure captions, and public post titles. Use the All, Used, Unused, Cover, and Recently added views, or choose a sort order from the toolbar.

Each card includes Copy Markdown and Copy URL actions. Both actions use the canonical src value from the inventory. For example:

![Workshop](https://dropper.wayl.one/file/workshop.webp)

Trusted Dropper URLs may use resized URLs for previews. Those presentation URLs never replace the canonical URL in the JSON artifact or copied Markdown.

Image discovery #

The inventory includes:

Markdown image syntax, supported raw HTML <img> elements, and referenced <video>/<source> elements
normalized visible text from associated Markdown or HTML <figcaption> elements, including captions shared by multiple media elements in one figure
image, video, cover, cover_image, og_image, social_image, thumbnail, featured_image, hero_image, avatar, and author_image frontmatter
Image and video files below assets_dir

The image frontmatter field is a cover fallback. If cover or cover_image has a non-empty value, that field remains the first cover choice. Video URLs are kept as video media with their video MIME type. The library renders them with a <video> element and uses an explicit poster field or the same derived poster convention used by feed and video cards.

Images supplied by an external ![embed](...) card are still inventoried, but they are marked with an Embed label. This distinguishes a remote OG image from an image authored directly in a post.

Skipped, draft, private, and unpublished posts do not create public usage relationships. Local files are mapped from the asset root to site-root URLs; for example, static/images/logo.png becomes /images/logo.png.

Private body isolation is strict: the image library never scans private Markdown, rendered HTML, captions, alt text, or remote URLs. Changing only a private body produces identical public image-library output. A private post may opt its public-safe cover frontmatter into the inventory, with cover_alt as its only allowed alt field. This creates metadata only: it never creates a uses[] relationship or contributes added_at/last_used_at. Other private image fields are ignored. Private frontmatter is not presumed public; consumers may use only explicitly documented public-safe fields. Keep private media outside assets_dir when it must not be published by the static asset writer.

Local canonical URLs escape path components while preserving /. For example, my photo#1%.png becomes /my%20photo%231%25.png; authored percent-encoded references deduplicate to that same record. Remote query strings are preserved for signed URLs, but URLs with user:password@host credentials are rejected. Referenced local media is resolved and hashed when it is below assets_dir, including an absolute assets_dir outside content_dir. Other local files are eligible when they are below content_dir; files outside both roots are ignored. Platform-native filesystem paths are supported, including Windows drive-letter paths.

The public uses[] entries contain the public href, title, caption, and flags. They do not contain repository-relative source paths.

The versioned v1 reader requires the documented top-level fields and the stable per-image fields (src, width, height, alt, mime_type, cover, and uses). Each usage requires href and cover. Unknown fields are ignored so newer producers can add metadata without breaking readers.

The JSON artifact is deterministic. Images are sorted by source URL and usage links are sorted by public href. Repository-relative source paths are not included in public usage records. A missing local dimension is reported as 0. Local PNG, JPEG, GIF, WebP, BMP, and TIFF files report their dimensions when the file metadata is valid. SVG files use positive width and height values or a positive viewBox; ICO files use their largest directory entry. AVIF and HEIC/HEIF records are supported, but their dimensions remain 0 until a decoder is available. Malformed or unsupported media does not fail the build.

Each used image includes added_at when a public post has a valid publication date; it is the earliest such date in UTC. last_used_at is the latest public publication date in UTC. These dates come from post frontmatter, not local file timestamps, so remote media and local media use the same rules. Missing values sort last. The Recently added view shows sources with a positive added_at timestamp from the last 30 days according to the browser clock. Each usage relationship can also include its figure caption. Captions stay with the usage relationship because one media source can have different captions in different posts.

The image library keeps a small media fingerprint cache for incremental builds. When a local file’s path, size, and modification time are unchanged, markata-go reuses its content fingerprint without reopening the file. On filesystems that expose an operating-system change time, that signal also detects replacements that preserve size and modification time. Filesystems without that signal must keep modification times reliable for this optimization; a changed, added, removed, or renamed media file with changed cache state invalidates the generated inventory.

The writer checks for collisions with posts, feeds, and static files before it writes. It does not overwrite an existing site file. When you disable the library or change its path, cleanup removes only files previously recorded as image-library outputs whose contents are unchanged. A modified or unowned stale JSON file is preserved and reported as a collision. Output paths that traverse symlinks below the configured output root are rejected for safety. Platform-managed ancestors above that root are allowed.

Custom templates #

Copy images.html into your site’s templates/ directory to customize the page. The template receives:

image_library — page counts and presentation-ready image cards
image_index — the canonical imageindex.Index
image_library_config — the resolved image configuration

Image cards expose IsVideo, PosterSrc, Embed, AddedAt, AddedAtUnix, LastUsedAt, and LastUsedAtUnix in addition to the regular image fields. AddedAt is the earliest valid public post date for the source. Each item in Uses can also expose Caption when the media appears inside a figure. Custom templates should render IsVideo cards with a <video> and <source> rather than an <img>.

The bundled page keeps video URLs out of active src and <source src> attributes in the initial HTML while keeping the poster active as the card’s thumbnail. Its JavaScript loads each video when its card enters the viewport, so an image-library page with many videos does not fetch every video at once. Without JavaScript, the card still links to the canonical media URL.

The server-rendered page remains useful when JavaScript is unavailable. The bundled JavaScript only enhances filtering, sorting, usage expansion, copy feedback, and video loading.

See the configuration reference and built-in plugin reference for related settings.

Optional server-side pagination #

For large libraries, avoid sending every image card on the initial request:

[markata-go.images]
page_size = 48

With this opt-in setting, /images/ renders up to 48 cards and emits native /images/page/2/, /images/page/3/, etc. links. The JSON inventory still contains all public media; no published media relationships are lost. The page links work without JavaScript. Global search, filters, and sort are still available with JavaScript: on the first interaction the browser retrieves the other static HTML pages and searches across the complete collection, instead of loading all their DOM nodes during first paint. Until that interaction, the initial page stays light and usable. If another page fails to load, the links remain available for ordinary browsing.

A setting of page_size = 0 (default) preserves the existing single-page library. Sites with a custom images.html should update their template to honor image_library.PageLinks before enabling pagination.

Content Diagnostics Ledger Design

2026-09-10T00:00:00Z

Decision #

Use one manager-owned diagnostics.ContentLedger. The ledger stores per-source state and derives the build summary from those entries. The manager already owns discovered files, posts, feeds, stage execution, and reset behavior, so it is the smallest place that can connect all lifecycle boundaries without a new parallel content inventory.

The existing diagnostics.Issue remains the shared issue shape for source positions and severities. Frontmatter analysis lives beside those checks and is reused by the loader. The loader continues to be strict for direct parser callers, but a content parse failure is recorded for that candidate and does not prevent valid sibling files from reaching later stages.

State Model #

Each discovered path records candidate status, source load status, frontmatter presence and validity, post creation, public eligibility, render, emission, diagnostics, reasons, and feed-level selection. Final disposition is derived from those fields as emitted, shadow, excluded, or not_candidate.

The snapshot sorts paths, reasons, feed names, and diagnostics. Ledger mutation is synchronized because rendering and writing use worker pools. Duplicate issues are ignored by their stable source/code/message identity.

Frontmatter Policy #

The parser recognizes an exact first-line ---, after an optional UTF-8 BOM. A longer hyphen run, such as ---- or -----, is only called suspicious when the following lines look like a YAML metadata block and an exact closing delimiter exists. This avoids warnings for ordinary Markdown horizontal rules. Leading whitespace before a frontmatter-like opening is diagnosed but is not silently normalized. Missing and malformed closing delimiters are diagnosed. No-frontmatter Markdown remains valid and quiet.

Reporting and Testing #

Build summaries show counts for discovery, candidates, loading, valid frontmatter, posts, eligibility, rendering, emission, exclusion, warnings, and errors. Normal warnings include a relative path and line. build -v explains each excluded or shadow source and its reasons. The existing benchmark JSON surface carries the sanitized ledger snapshot for later consumers.

The regression suite uses temporary real sites and runs the actual glob, load, render, feed, and write plugins. It covers valid frontmatter, no frontmatter, the production ---- case, -----, malformed and missing closing delimiters, leading whitespace, BOM, invalid YAML, duplicate keys, invalid metadata types, invalid dates, empty frontmatter, and ordinary Markdown controls.

Content Diagnostics

2026-09-10T00:00:00Z

After a successful full build completes, markata-go writes a sanitized diagnostics artifact below the configured output directory:

<output_dir>/.markata/diagnostics.json

For example, a build with -o dist writes dist/.markata/diagnostics.json. The artifact is enabled by default. It is part of the generated output, so a Builder Admin release from such a build carries it with the rest of the site.

Inspect the artifact #

Use a JSON viewer such as jq:

jq . public/.markata/diagnostics.json
jq '.executor' public/.markata/diagnostics.json
jq '.summary' public/.markata/diagnostics.json
jq '.entries[] | select(.disposition == "excluded")' public/.markata/diagnostics.json

Replace public with the output directory used by the build. There is no separate diagnostics command or generated public HTML page.

Stable fields and reason codes #

The top-level schema, schema_version, generator, built_at, executor, summary, and entries fields are stable parts of the versioned format. Consumers must check both schema and schema_version before interpreting the document.

executor records the build engine that produced the artifact. Normal builds report legacy; builds explicitly using the feature-flagged DAG executor report dag. The same identity is included in markata-go build --benchmark-json output, which makes local benchmark reports and Builder Admin release artifacts unambiguous without parsing human-readable logs.

summary contains counts for discovered files, candidates, loaded sources, valid frontmatter, posts, eligible posts, rendered posts, emitted outputs, excluded candidates, warnings, and errors. Each entry includes a relative source path, lifecycle state booleans, a final disposition, sorted reasons, diagnostics, and feed-level dispositions.

Feed dispositions are complete: feeds that did not include a source remain in the artifact with their exclusion reasons. On large sites this can make the JSON file substantial. Full builds stream one sanitized entry at a time instead of constructing full-artifact serializer buffers, reducing temporary memory without dropping observations or changing the indented JSON format. The immutable ledger snapshot and final file still contain the complete diagnostics; there is no additional configuration to enable this behavior. Snapshot construction copies feed reasons into one owned arena per entry, with each feed’s slice capacity clamped even after deduplication. Appending or mutating one feed cannot change sibling feeds, the ledger, or another snapshot. Every snapshot remains a fresh copy; counts, ordering and empty-value semantics are unchanged. Fewer small allocations do not imply a reduction in whole-build RSS.

Reason codes are stable identifiers. Messages can change without changing a code. The current codes cover:

frontmatter: frontmatter.suspicious_delimiter, frontmatter.leading_whitespace, frontmatter.malformed_closing_delimiter, frontmatter.missing_closing_delimiter, frontmatter.parse_error, frontmatter.duplicate_key, frontmatter.invalid_type, and frontmatter.invalid_date;
content and output: content.published_false, content.draft, content.skip, content.private, content.filtered, content.duplicate_slug, content.no_output, content.load_error, content.render_error, and content.write_error;
feed windowing: feed.offset and feed.limit.

The artifact uses schema markata.content-diagnostics and schema version 1. Older version-1 artifacts created before executor reporting may omit the executor field; readers should treat that as unknown rather than infer it from other fields.

Template cache decisions #

Completed template rendering adds an optional template_cache object to the version-1 artifact, and to content in benchmark JSON:

jq '.template_cache' public/.markata/diagnostics.json
jq '.content.template_cache' benchmark.json

Older version-1 artifacts without this object remain valid. It is independent of the profiler and contains bounded counts, not per-page cache diagnostics. classified counts non-skipped posts (including empty bodies); skipped is separate. cacheable counts metadata hits, restored counts usable full-page hits, and render_required includes misses later deferred by incremental serve. render_succeeded and render_failed count selected render results; serve_deferred counts pages excluded by the canonical incremental selection. A best-effort cache write failure does not turn a successful render into failure.

Bounded parallel restoration does not change these counts or the artifact schema. All reads finish before fresh templates run; restored peer pages remain visible through Core. Unavailable pages retain their deterministic input order after classification misses, and an existing in-memory full-page hit remains usable even if its disk file is gone. Template phase logs measure classification, restoration, and fresh rendering separately, including zero-render builds; aggregate counts alone are not disk-read measurements.

miss_reasons reports only the first failing gate, in this order: affected_path, cache_unavailable, input_hash_missing, entry_missing, input_hash_mismatch, template_mismatch, dependency_changed, slug_changed, feed_membership_changed, local_preview_changed. A metadata hit can instead fall back to rendering with full_html_unavailable when the full-page getter returns empty. Empty cached input hashes are partial entries compared normally, not evidence of corruption. Empty or unavailable full HTML is not a corruption claim either.

Earlier reasons mask later ones; the histogram does not enumerate every possible reason. nav_preview_reset reports whether shared navigation metadata reset the page cache in this invocation, not proof that each miss was caused by navigation. Repeated invocations replace the observations rather than accumulating them.

To reconcile counts:

classified - cacheable = sum(first ten reasons)
cacheable = restored + full_html_unavailable
render_required = sum(all eleven reasons)
classified = restored + render_required
render_required = render_succeeded + render_failed + serve_deferred

Expect cold-build misses and some recurring misses. Persistent misses are not automatically bugs: compare equivalent warm builds and their aggregate reasons before investigating invalidation. Timing varies with host activity and I/O. These counts contain no paths, template names, hashes, secrets, or per-page labels, and add no telemetry I/O. This is the template-cache portion of #1339; publish-I/O diagnostics are not implemented by this phase.

Unchanged private posts and encryption changes #

Source-encrypted posts are parsed on every build to avoid caching decrypted Markdown or article HTML. Their inferred titles are compared using canonical post-transform hashes from the previous build, not the temporary untitled values produced during Load. Losing a plain post’s parsed cache follows the same rule. The handoff is transient and hash-only; diagnostics gain no titles, decrypted bodies, passwords, or per-private-post debug paths.

Changing a password, key name, hint, or encrypted-wrapper format, or losing the encrypted wrapper cache, legitimately regenerates a wrapper. Encryption marks the source path and dependent pages for fresh templates and publication, including an empty-slug homepage. These misses use affected_path, not a new diagnostic reason. An unchanged valid wrapper hit does not add affected paths. An existing page can have missing semantic metadata immediately after a cold navigation reset. Those missing hashes are treated as an unavailable baseline, not evidence that the post is new. A subsequent edit therefore keeps unrelated pages cacheable while repairing canonical hashes, without requiring an extra warm-up build. Regeneration also clears the old full-page cache reference. If fresh page-cache storage fails, the next persisted reload re-renders using the current wrapper and reports full_html_unavailable; it cannot restore the old-password page. Load may still conservatively dirty feeds, tag indexes, or garden metadata; this fix does not clear those signals or address deletion drift (#1465).

Privacy and publication behavior #

Feed collection retains every considered source occurrence and exclusion, including feeds whose publishing work is skipped. Ordered per-feed recording is atomic with respect to ledger snapshots: the last observation controls inclusion, while reasons are unioned and excluded observations also contribute entry reasons. Duplicate raw paths and normalized aliases are not discarded during selection. Collection scratch is invocation-local, and later builds refresh flags and membership. The bounded auto_feeds / collect debug record separates generation, filtering/sorting, selection recording, and pagination/preparation durations and counts without paths, feed names, or new artifact fields.

New batch feed relationships use owned slabs capped at 10 dispositions or 32 initial-reason string slots, with smaller tails bounded by remaining observations. Raw lists above 32 strings use ordinary standalone append/deduplication, not reservation by raw length or a counting pass. Retained storage grows with unique nonempty values. Reasons are copied and deduplicated in occurrence order; slab segments are disjoint and capacity-clamped, so later updates cannot append into a neighbor. Published storage is never cleared or reused. Only missing candidate relationships allocate slabs. Existing updates and ordinary single-record producers do not use this allocator; there is no registry or cross-build pool. Snapshots remain independently owned even after ledger reset or rediscovery.

Streaming reuses owned sanitation scratch sized by the largest entry. Within one publication it also reuses standard-encoded feed fragments, capped at 1024 fragments and 1 MiB of combined keys and JSON bytes. Overlarge or high-cardinality values are still encoded completely, without retention. Nothing is cached across builds; the snapshot and final file still grow with all recorded observations. The schema, ordering, escaping and indented bytes are unchanged. Publication uses a fixed 64 KiB file buffer, checked on flush before sync, close and replacement. Large individual writes can bypass buffering, so raw-write counts must be measured rather than inferred from artifact size divided by the buffer size. These improvements concern temporary serialization storage, not whole-build RSS: live templates and rendered HTML still retain their own memory.

The diagnostics_artifact cleanup debug record separates snapshot, source_metadata, serialization_buffering_exclusive, file_write, flush_exclusive, sync, close, and replace. file_write_bytes and file_write_calls count actual underlying file writes, not buffered calls. Serialization/buffering and flush exclusive durations exclude those file writes. Their separately labeled inclusive wall totals overlap file-write time: do not add them to the exclusive components. Source metadata includes the optional Git lookup; missing Git metadata is still harmless. These elapsed measurements contain no paths or messages and are not tracing spans or fields in the artifact. Directory/temp setup and temp removal are outside these phases; published=0 means replacement did not complete.

The artifact contains sanitized ledger data only. It does not contain raw configuration, environment values, secrets, absolute paths, raw logs, frontmatter, Markdown bodies, rendered HTML, decrypted private content, or encryption key names.

The file is published only after the normal full lifecycle completes. A failed build leaves an existing artifact unchanged and does not leave a partial new file. Streaming output is flushed, synced, and closed in a temporary sibling file before replacing the artifact; serialization or write failures leave the previous artifact intact and fail the build. markata-go build --dry-run, markata-go build --fast, partial lifecycle calls, and fast or incremental development server requests do not publish a new artifact. A normal serve build may publish one when its full build completes successfully.

PostIndex Correctness and Consolidation

2026-09-03T00:00:00Z

Goal #

Keep lifecycle.Manager.PostIndex() correct across manager resets and use it where an existing production lookup has the same source, key semantics, and lifecycle. Do not replace filtered collections, cache snapshots, validation indexes, or aggregation maps.

PostIndex contract #

PostIndex() builds lazily from the manager’s current post slice. It is not restricted to the end of Load; any plugin can request it at any stage. The manager invalidates the cached index after SetPosts, AddPost, and Reset.

Key	Behavior
Slug	`BySlug` uses lowercase `Post.Slug`; `LookupBySlug` tries this first
Slugified	`BySlugified` uses `models.Slugify`; lookup tries it second, then the slugified key in `BySlug`
Href	`ByHref` uses the exact non-empty `Post.Href`
Path	`ByPath` uses the exact non-empty `Post.Path`
Aliases	String aliases use lowercase and slugified keys; existing alias entries are not overwritten
Duplicates	Main slug, slugified slug, href, and path entries are last-post-wins
Nil	Nil index receivers and misses return nil from `LookupBySlug`; nil posts are not valid index input

The maps are shared pointers to the posts, not copies of post values. A direct mutation of Slug, Href, Path, or alias data on an existing post does not invalidate the index. Such a mutation requires PostIndex().Refresh(m) before the next lookup. Refresh is used once by the wikilinks transform because other plugins may have changed post fields before that consumer runs.

Lookup inventory #

Component	Lookup key	Current implementation	Lifetime	Source of truth	Equivalent to PostIndex?	Can replace safely?
Embeds	slug	Shared `PostIndex.LookupBySlug`	Transform	Manager posts	Yes	Already uses it
Wikilinks	slug	Shared `PostIndex.LookupBySlug` plus one refresh	Transform	Manager posts	Yes	Already uses it
Wikilink hover	href with slash variants	Shared `PostIndex.ByHref`	Render	Manager posts	Yes, with consumer normalization	Already uses it
Link collector	slug/href with slash normalization	Shared `PostIndex` maps	Render	Manager posts	Yes, with consumer normalization	Already uses it
`include_post` template function	exact trimmed slug	Linear `Manager.Posts()` scan	Render/template call	Manager posts	No: case, slugification, alias, and duplicate semantics differ	No
Post service `Get`	exact path	Linear `Manager.Posts()` scan, first match	Service lifetime	Manager posts	No: `ByPath` is last match on duplicates	No
Prev/next	post slug to feed membership	`map[string][]*Feed`	Collect call	Selected feed posts	No: membership and order are the result	No
Templates/sidebar	current slug in selected feeds	Linear membership/position scans	Render/collect call	Selected feed posts	No	No
Mentions	configured post filter	Collection scan and filter	Transform	Manager posts	No: aggregation/filtering	No
Slug conflicts	normalized slug to all paths	`map[string][]string`	Validation call	Publishable posts	No: duplicate reporting is intentional	No
Search	path to visible post	Filtered `search.PostsByPath` map	Search request/index	Search-visible posts	No: drafts/skips are excluded	No
Search API	path to visible post	Handler-owned snapshot map	Handler lifetime	Handler update snapshot	No: independent lifecycle	No
List cache	source path	Cache reconstruction map	Load/cache operation	Cached files and feeds	No: needed before the manager collection is final	No
Incremental serve/load	source path	Cached post maps	Build/serve cycle	Serve or build cache	No: cache state	No
Publish HTML	path to slug	Transient invalidation map	One write operation	Current post paths and cache	No: reverse projection	No
Content index	path eligibility	Filtered eligibility map	Content-index operation	Content-index policy	No: eligibility is the value	No
LSP	slug/URI to `PostInfo`	Separate locked workspace index	LSP session	Workspace files	No: separate model and lifecycle	No

No local post lookup map met all four replacement conditions: identical source posts, normalization, lifecycle visibility, and duplicate/result semantics.

Lifecycle decision #

Synthetic posts are added with AddPost during Configure or late Load, so they invalidate the index before Transform consumers run. A consumer that needs a filtered subset or a cache-owned snapshot must keep its local lookup. No plugin is changed to use the shared index solely to reduce a small loop when doing so would change normalization or duplicate behavior.

Verification #

The regression sequence is:

Set post A and build the index.
Reset the manager.
Confirm the manager has no posts and its next index cannot find A.

Additional tests cover SetPosts, AddPost, slug case and slugification, href/path keys, duplicate behavior, direct field mutation followed by explicit Refresh, and the nil lookup receiver.

Build Lab

2026-08-31T00:00:00Z

Build Lab compares a baseline binary with a candidate binary. It runs each build in an isolated temporary workspace and records output manifests and correctness checks. It runs ordinary markata-go build commands. It does not use a task graph or scheduler flags.

Build Lab copies the fixture, redirects cache and temporary paths, disables fixture .env loading, and pins child processes to UTC, C.UTF-8, and SOURCE_DATE_EPOCH=0. Custom plugins, arbitrary binaries, and fixture content remain trusted inputs. Process groups or Windows Job Objects provide best-effort descendant cleanup; they are not an operating-system sandbox.

Run a smoke comparison #

Build the binary first:

go build -o /tmp/markata-go ./cmd/markata-go
markata-go buildlab run \
  --fixture /path/to/site \
  --baseline /tmp/markata-go \
  --candidate /tmp/markata-go \
  --result buildlab-result.json

Each checkpoint compares:

clean baseline output with clean candidate output;
candidate incremental output with clean candidate output; and
two clean candidate builds when determinism checking is enabled.

The default scenario performs a cache/output cleanup, a priming build, and a no-op incremental build. Use --fast for a quicker smoke check. Fast mode is not a substitute for a full production-output comparison.

Use a scenario file #

Scenario files contain an identifier, version, seed, and ordered operations:

{
  "id": "title-change",
  "version": "1",
  "seed": 42,
  "operations": [
    {"type": "build"},
    {
      "type": "replace-exact",
      "path": "content/foo.md",
      "old": "title: Old",
      "new": "title: New"
    },
    {"type": "build"}
  ]
}

Run it with:

markata-go buildlab run \
  --fixture /path/to/site \
  --baseline /tmp/markata-go \
  --candidate /tmp/markata-go \
  --scenario title-change.json \
  --result buildlab-title-change.json

Build Lab supports build, write-file, replace-exact, delete-file, rename-file, copy-file, set-config, touch-file, clean-cache, and clear-output. Paths stay inside the fixture, and replace-exact must match exactly one occurrence. Semantic mutations must be followed by a build.

The foundation covers clean, no-op, edit, add, delete, rename, linked-target, and configuration mutations. Add fixture-specific scenarios for other product surfaces.

A linked-target checkpoint compares the dependent page and its feed outputs. The incremental build must rerender known dependents before feeds and pages are written. Unrelated posts must remain eligible for cache hits.

Read failures correctly #

Build Lab is a measuring instrument. A result with failure_class: "product" means that a child build or an output comparison found a Markata-Go behavior problem. It does not mean that the harness should be changed to hide the problem. A failure_class: "harness" result means that the comparison itself was not trustworthy, for example because of a timeout, output truncation, path violation, or manifest error.

Product failures include concise diagnostics in the JSON result and on stderr. Known failures can therefore be recorded while the foundation remains focused on measurement.

Setup errors also emit a versioned JSON result with failure_class: "harness" when the command reaches the Build Lab runner. Invalid command-line syntax is reported by the normal CLI parser instead.

Output classes #

Manifest records are deterministic by default. Known minification and fontpack metadata files are excluded because they are build state, not publishable output. Use --volatile for known changing publishable paths, such as the default .well-known/time file:

markata-go buildlab run --fixture /path/to/site --volatile .well-known/time

Use --check-determinism=false only when a fixture cannot support the clean rebuild check. Keep that exception visible in CI configuration.

Isolation and environment #

Use the global --merge-config flag to apply a fixture-local profile to both child binaries:

markata-go buildlab run --fixture /path/to/site --merge-config fast.toml

The --env option accepts only PATH, MARKATA_GO_ENCRYPTION_ENABLED, and MARKATA_GO_OFFLINE. Build Lab does not inherit arbitrary environment variables, including proxies, cloud settings, Git settings, agent settings, or credentials.

markata-go buildlab run \
  --fixture /path/to/site \
  --env MARKATA_GO_ENCRYPTION_ENABLED=false

Use --timeout and --gomaxprocs to control execution. Record external tool versions with repeated comma-separated entries:

markata-go buildlab run \
  --fixture /path/to/site \
  --tool-version pagefind=1.5.2,tailwind=4.1.0

Content Index

2026-08-15T00:00:00Z

Markata can write one compact JSON file with the metadata it resolved during a build. It does not include article bodies.

[markata-go.content_index]
enabled = true
output = "content-index.json"

The file is written below output_dir unless output is absolute. Its identity is schema = "markata.content-index" and its current generation is schema_version = 2. V2 emits scope = "public-metadata". This means the file can contain safe metadata records for private posts; it never contains their article bodies or encryption keys.

Reading the file #

Read schema and schema_version before decoding. Ignore fields you do not know. If the generation is newer than the reader supports, stop with a clear upgrade message. Do not guess how a future generation works.

Use each document’s repository-relative path to find its source file. The feeds array already contains resolved Markata feed membership. Consumers should not implement Markata’s feed filter language again.

Documents may also include optional resolved frontmatter and author metadata: image, video, avatar, bio, thumbnail, cover, og_image, author, authors, category, and categories. Media values are source references; Markata does not copy or download those assets into the index. Author order is preserved. cover uses cover first and cover_image as a compatibility fallback. og_image uses og_image first and social_image as a fallback.

source.commit identifies the Git HEAD observed for the build. source.dirty is false when the working tree was observed clean at the Content Index source-state boundaries. It is true when Git reports tracked, staged, deleted, untracked, or ignored Markdown source files. Compare both values with the source repository revision before using metadata as a bootstrap cache. Both fields are absent when Git cannot provide source state. Markata captures this state before content discovery and rechecks it before writing. A changing source state fails an enabled index write instead of publishing a mismatched identity.

The pair source.commit plus dirty: false is build provenance. It does not prove that every document came byte-for-byte from a blob in that Git revision. A source file can change and be restored between the two observations. Use Git commit/blob identity, or another exact source identity mechanism, when exact per-file synchronization is required.

The index includes non-draft, non-skipped posts, including private posts. A published: false direct page may still appear. A feed named draft is feed membership only and does not mean that the document has draft: true.

Private records contain only safe metadata. Titles and descriptions are present only when they were explicitly provided in frontmatter; content-derived values, article bodies, rendered HTML, key names, private media, and resolved author biographies are omitted. Tags, dates, slugs, aliases, author identifiers, categories, and an explicit avatar may remain. The feeds list for a private record contains only feeds configured with include_private = true (or private = true).

Markata retains readers for every released generation and normalizes them into one current internal model. The index is not a source archive, rendered-body cache, access-control system, or guarantee that source files remain available. If you disable the output, use a clean output directory or remove the old artifact before deployment.

The v1 and v2 schemas and immutable interoperability fixtures are in pkg/contentindex/v1_schema.json, pkg/contentindex/v2_schema.json, and pkg/contentindex/fixtures/. Set schema_version = 1 when a consumer still requires the public-only v1 artifact.

Rendering migration merge-readiness evidence

2026-08-10T00:00:00Z

This record closes the rendering-contract acceptance checklist. It does not claim full application WCAG compliance or exact cross-browser pixel parity.

Commands and outcomes #

Markata-Go #

All commands passed:

go run ./scripts/rendering-contract --check
go test ./...
go vet ./...
go build ./cmd/markata-go
go test ./pkg/renderingcontract -run TestContract_FinalRenderSweepCoversEveryCanonicalPalette -count=1
git diff --check

The final CSS projection sweep audited 120 canonical variants: 120 audited, 120 passing, 0 failing. The contract contains 60 light/dark families.

Theme Lab #

All commands passed:

bun test                         # 10 pass, 0 fail
just browser-regression          # 3 pass, 0 fail, 45 assertions
git diff --check

The browser matrix uses brush-poster, waits for the Knewave font load, checks H1-H6 fixture geometry and bounds, and captures six generated screenshots: none, splatter 0, splatter half, splatter full, dry-brush half, and screenprint half. The zero/none geometry is equal, intermediate/full and recipe masks differ, and the headings remain inside the preview bounds.

Plaindown #

Focused and browser checks passed:

bun test tests/markata-theme.test.js tests/editor-theme-accessibility.test.js tests/render-plan-fixtures.test.js
just browser-regression          # 22 pass, 0 fail, 130 assertions across 2 browser files
git diff --check

The browser files include two Plaindown rendering-regression tests plus the existing browser smoke tests. The suite asserts both Site and Editor mode states, including Site-mode canonical variables and Editor-mode ownership.

The full suite is a baseline, not a rendering gate:

current worktree: 415 pass, 18 fail, 2 errors
origin/main:     389 pass, 20 fail, 4 errors

The 16 named assertion failures are identical in both runs: selectable-hunk review, draft/discard persistence, file-tree actions, navigation aliases, frontmatter media completion, semantic preview routing, remote update actions, wikilink resolution, stale-route recovery, draft deep links, live-preview debouncing, and repository-content sweep checks. The two unhandled errors are environment/dependency failures (@codemirror/*/vendor fflate), not rendering changes.

Evidence boundaries #

Go, Theme Lab, and Plaindown intentionally use different rendering recipes: Go emits generated site CSS, Theme Lab is the visual reference, and Plaindown owns editor chrome while Site mode projects the contract. Their shared evidence is normalized state, complete render plans, semantic roles, and final CSS variables—not identical implementation details.
Plaindown browser endpoint checks exercise texture, heading-mask, and motif values at 0, 0.5, and 1. They verify readable heading contrast and that motif color mix changes the image, not layer opacity.
Plaindown editor source-to-final-variable accessibility uses the separate editor projection audit for every editor-owned theme plus representative browser checks of final body, muted, and boundary variables.
Chromium is available and passes. Firefox/WebKit smoke execution is not claimed: installed browser binaries are older than the Playwright package’s requested revisions, and no large download was performed.

Repository hygiene and payload #

The intended files are the source, tests, generated contract projections, docs, checklist, and Theme Lab package.json/bun.lock. Theme Lab node_modules/ and test-results/ are ignored and are not intended for the PR. Browser screenshots are transient review artifacts.

The contract JSON and generated consumer contract are about 34.7 KB and 39.6 KB respectively. Theme Lab’s HTML is about 160 KB; Plaindown’s rendering contract and theme module are about 39.7 KB and 38.8 KB. Theme Lab declares all font families in one CSS import for its catalog, but font-face files are requested by browser use; no 120-palette asset requests were observed.

The public authoring names audited and frozen are palette, aesthetic, fontpack, the nested texture, heading_texture, and motif fields, and variables. No accepted public field is silently ignored.

Rendering presentation contract

2026-08-09T00:00:00Z

Markata-Go uses rendering contract version 1 for portable presentation settings. The authoring source is spec/rendering-contract/contract-v1.json.

Canonical configuration #

Put theme-level settings under [markata-go.theme]. Put texture, heading texture, motif, and variable settings under their nested tables.

[markata-go.theme]
contract_version = 1
palette = "ayu-dark"
aesthetic = "minimal"
fontpack = "brush-poster"
custom_css = "custom.css"

[markata-go.theme.texture]
kind = "screenprint"
color_mix = 0.35
scale = 1.0
scope = "all"

[markata-go.theme.heading_texture]
kind = "inherit"
color_mix = 0.45
scale = 1.0

[markata-go.theme.motif]
kind = "block-w"
glyph = "W"
size = "78px"
gap = "10px"
row_offset = 0.24
wobble = 0.18
scatter = 0.0
layer = "sandwich"
color = "ink"
color_mix = 0.01
url = "https://waylonwalker.com/w.svg"

[markata-go.theme.variables]
"--content-width" = "68ch"

The motif is off by default (kind = "off"); the example above enables the block-w motif explicitly.

In TOML, a key belongs to the current table until another table header appears. Keep custom_css in [markata-go.theme], not in motif.

Contract values #

The contract defines the shared IDs, defaults, enums, and bounds. Use its palette IDs, aesthetic IDs, fontpack IDs, texture kinds, heading texture kinds, motif kinds, colors, layers, and scopes.

The canonical dials use numbers:

color_mix, row_offset, wobble, and scatter: 0..1
texture.scale and heading_texture.scale: 0.25..3

heading_texture.kind = "inherit" uses the surface texture kind while keeping the heading texture’s own mix and scale.

Fontpacks assign the named roles body, heading, and mono. Select a fontpack instead of inventing role names in site configuration.

Migration from flat settings #

Contract version 1 accepts legacy flat settings as migration inputs. Canonical nested values always win when both forms are present. The loader reports a warning when the values conflict. Canonical serialization emits only nested settings.

The legacy texture_scope = "headings" value means headings-only behavior. Do not convert it to theme.texture.scope = "headings"; headings is not a canonical scope. The migration keeps the texture kind in theme.heading_texture.kind and sets the surface texture scope to quiet.

Other documented aliases include texture_strength, heading_texture_strength, motif_color_distance, texture_scale, heading_texture_scale, motif_row_offset, motif_wobble, motif_scatter, motif_layer, and motif_color. See spec/rendering-contract/MIGRATIONS.md for the complete mapping.

Add or change contract data #

Change contract-v1.json first when you add a shared palette family, palette variant, fontpack, aesthetic, texture, motif value, default, bound, or alias. Do not edit generated projections by hand. Regenerate them from the repository root, then run the generated-artifact check:

go run ./scripts/rendering-contract
go run ./scripts/rendering-contract --check

The generator also targets supported consumer repositories. Run it only when those repositories are available, and do not add a local registry instead.

New site #

Start with the canonical example above. Select one palette ID, aesthetic, and fontpack. theme.fontpack accepts contract fontpack IDs and any pack or alias in the font catalog (markata-go fonts packs, or your fontpacks_file). Validate the site with the contract check and the focused configuration tests before adding local variables.

New palette #

Add the family and both light and dark variants to contract-v1.json. Include explicit family, variant, name, and semantic role metadata. Regenerate all projections and run the 120-variant final-CSS sweep.

New dial #

Add the field, default, bounds, and migration alias to the contract first. Then update normalization, serialization, render plans, CSS projection, completion, and browser fixtures in Go, Plaindown, and Theme Lab. The drift check must pass before the dial is accepted.

Validation #

Check a palette after changing its roles or colors:

markata-go palette check ayu-dark
markata-go palette check ayu-dark --strict

Run go run ./scripts/rendering-contract --check after contract changes. Run go test ./pkg/config ./pkg/renderingcontract to exercise configuration migration and contract loading.

WCAG AA color gate #

The rendering/theme gate checks the final semantic projection used by generated CSS. Normal text, metadata, headings, links, code tokens, and button text use 4.5:1. Controls, focus indicators, borders that identify controls, status colors, and other non-text UI use 3:1. A role is not treated as large text because its name says muted, secondary, or comment.

Decorative texture, motif, and shadow layers have no independent contrast target, but their mix and opacity must not lower readable content below these limits. AAA is reported separately and is optional.

The canonical palette sweep validates every catalog variant and records the final foreground/background pair and ratio. Plaindown Editor themes use a separate sweep because Editor mode owns its chrome; Site mode uses the canonical Markata palette projection. Both sweeps are required before changing a palette or editor theme.

Font packs

2026-08-06T00:00:00Z

Markata defaults to the offline system pack. It makes no external font requests and emits no font binaries. To choose another pack, add this to the site configuration:

fontpack: system-reader

The same value can be set as theme.fontpack. Any pack or alias listed by markata-go fonts packs is valid. When fontpacks_file is set, names are checked against that catalog when the site builds.

Catalog-defined bundled packs use vendored, stable WOFF2 tiers. The built-in catalog, manifests, licenses, and font assets are embedded in the executable, so these packs work from an installed or GoReleaser binary in any working directory. Bundled builds do not run Python or FontTools during markata build.

The generated css/fonts.css has a content-hashed URL for caching. Pages preload the emitted WOFF2 files for their body and main heading ahead of CSS; per-page overrides use their own pack. A stored picker choice is restored before paint and preloads that choice too. Nonempty editorial feeds also preload the code face used by their visible week labels, so layout does not have to discover that font later. Calendar controls reserve their space while loading to keep the archive toolbar stable. Shared sources are fetched once, and system code stacks need no download. Other layouts keep code fonts on demand. Additional script coverage also loads when needed. Font faces use font-display: swap, so slow networks can still briefly show fallback text; preloading reduces that delay without forcing fallback fonts permanently.

System packs use local system stacks and transfer zero font files. Custom packs are loaded from an explicit catalog and may reference local assets. Relative paths in a custom catalog are resolved relative to the catalog file, not the current working directory.

Inspect the catalog with:

markata-go fonts packs
markata-go fonts show system
markata-go fonts doctor
markata-go fonts verify
markata-go fonts report

Compare packs on one site #

Painted Sign #

painted-sign combines Finger Paint display lettering with scratchy Rock Salt headings and accents over a clean Source Sans 3 prose stack. DM Mono remains available for code, so the expressive hierarchy does not compromise reading.

The fontpack frontmatter field overrides the site default for one page:

---
title: "Brush comparison"
fontpack: brush-poster
---

All selected page packs share one generated stylesheet and deduplicated asset set. The comparison pages in pages/post/test-*.md use this mechanism.

Markata tracks emitted files in output/assets/fonts/.markata-fonts.json. Switching packs removes obsolete Markata-generated files while preserving unrelated user-managed files in the same directory.

On warm builds, pages that already select the resolved pack keep their existing HTML rather than copying the page body just to reapply the root attribute. Changing the site or per-page pack still updates data-fontpack; custom attributes and quoted values on the HTML element are preserved. Font catalog, glyph coverage, preloads, and missing output files are still checked normally.

Cold resolution streams article HTML through one shared visible-character analysis. Repeated characters and repeated pack selections do not repeat that work, and a family’s coverage checks stop once its full tier is required. This does not change font choices or run a subsetter during your build.

Built-in output caching tracks visible coverage, the default pack, effective pack choices, picker settings, and bundled catalog/manifest revisions. Reordering equivalent selections or using equivalent aliases does not invalidate the cache. Missing generated stylesheets or fonts are regenerated through the same accelerated resolver; custom catalogs still validate their asset checksums. A new cache schema or bundled metadata revision causes one fresh resolution.

Coverage is selected per font family. A family gets latin-ext only when its manifest provides that tier; otherwise Markata falls back to that family’s full tier, so expressive faces without extended subsets still render all text. Role weight, style, size, and optical_size values are emitted as CSS properties and applied to the corresponding body, heading, code, lead, quote, and caption elements. When multiple packs are used, role variables and declarations are scoped to [data-fontpack="..."]; optional properties from one pack cannot affect another pack. A missing specialized role falls back to body as a whole, but an existing specialized role does not inherit optional properties that it did not configure. For example, a quote role without optical_size will not pick up the body’s optical-size setting.

The maintenance generator reads variable-font fvar axes from the source font, including their real weight and optical-size bounds. To check generated manifests without rewriting them, run it with --check and the pinned google/fonts checkout.

Regenerate the comparison pages after changing the catalog with:

uv run --with pyyaml python scripts/generate_fontpack_demos.py

Terminal UI

2026-08-02T00:00:00Z

Launch the terminal UI with markata-go tui.

The interface appears immediately with a loading state while site data is prepared in the background. You can quit during loading; navigation becomes available when the initial data arrives.

The TUI reuses .markata/cache/list.json between launches. It checks file metadata and the configured globs, then refreshes only changed posts. Ignored directories are skipped during discovery, so generated output and dependency trees do not need to be scanned. On a cold cache, changed posts are parsed in parallel, including source-encrypted posts.

Filter the posts you can see #

Press / in the posts or feeds view and start typing. Results update immediately and are limited to the items currently in the list. Post matching checks the title, path, description, tags, and content; feed matching checks the feed name, title, and path. Press Enter to keep the filtered list, or Esc to cancel and restore the list.

This is intentionally a simple list filter; it does not parse filter expressions. Use the regular CLI list command when you need structured filters.

Feed inventory #

Press f to open the feed inventory. It includes every configured feed, including private-enabled, sidebar-hidden, and automatically generated feeds. Their titles include explicit labels such as [private], [hidden], and [auto]; the labels are also color-coded when the terminal supports color.

Press Enter on any feed to view its posts.

CLI Output

2026-07-29T00:00:00Z

Markata uses your configured site palette for interactive help, status output, and section headings. Help sections use Unicode box-drawing rules sized to your terminal, up to 80 columns.

markata-go --help
markata-go lsp --help

When output is redirected, or when you pass --no-color, Markata keeps the same text and separators but removes ANSI color codes. Structured output such as JSON, YAML, and TOML remains suitable for scripts.

Builder Admin

2026-06-27T00:00:00Z

The builder admin service keeps a warm markata-go build worker running inside your cluster.

Instead of starting a new Kubernetes Job for every authoring build, it keeps one HTTP service alive with:

a serialized build queue
file watching that enqueues builds
build history and full raw logs
release history and current live release
the sanitized content diagnostics artifact from successful full builds
rollback by promoting an older rendered release
scheduled refresh tasks for reader, blogroll, or other remote-content commands
signed GitHub and Forgejo push webhooks that pull and build matching branches

What It Is Good For #

Use builder admin when:

your site content already lives on a mounted filesystem such as a hostPath
you care about fast authoring loops more than one-shot batch builds
you want an operator UI for builds and releases
you want remote-content refreshes to stay decoupled from normal content builds

Basic Helm Values #

builderAdmin:
  enabled: true
  port: 8080
  fast: false
  watch:
    enabled: true
    debounce: 2s
  releases:
    keep: 25
  history:
    successfulBuilds: 60
    failedBuilds: 100
    refreshRuns: 100
  refreshTasks:
    - name: reader-update
      every: 30m
      enqueueBuildOnSuccess: true
      args:
        - markata-go
        - --config
        - /data/source/markata-go.toml
        - reader
        - update

Build automatically after a new Builder image starts #

Helm enables builderAdmin.buildOnStartupRevisionChange: true by default. When the replacement Builder Admin pod acquires leadership, it compares the running binary’s embedded Git commit against the last successful real build. If the revisions differ, it immediately enqueues a normal full build with trigger startup-revision and records the comparison in build history. Publication remains atomic: a failed build keeps the last live release.

An unchanged restart does not enqueue another build. Existing pending normal builds suppress duplicates, and standby pods never enqueue during rolling updates. Before comparing revisions, the new leader reloads the previous leader’s persisted state. Rollbacks and failed builds do not count as successful builds for this comparison.

For older build records without a commit, Builder Admin checks the live diagnostics artifact. If neither source supplies a reliable previous revision, it performs one build to establish a baseline. A running executable without a reliable Git commit SHA does not automatically build based on a mutable image tag or development version.

Set builderAdmin.buildOnStartupRevisionChange: false to disable the Helm behavior. Helm injects MARKATA_GO_BUILDER_ADMIN_STARTUP_REBUILD as an environment variable instead of passing a new flag; older builder images ignore the variable, avoiding startup failures during staggered rollouts. Direct CLI use is opt-in via markata-go builder-admin --build-on-startup-revision-change.

Put transient build work on node-local storage #

By default Builder Admin preserves the historical behavior and creates .build-work under the release directory. For a write-heavy site whose durable site volume is slow at small-file I/O, move only the transient workspace onto node-local storage:

builderAdmin:
  workspace:
    enabled: true
    mode: emptyDir
    mountPath: /data/work
    workDir: /data/work/build
    emptyDir: {}

emptyDir is node-local and disappears with the pod. The next build safely seeds a new workspace from the current release. Retained releases and the current symlink remain under release-dir on the durable site volume.

Builder Admin retains an independent mutable workspace after publication. It creates a hidden staged release and compares its files with the previous immutable release. Matching file contents and permissions reuse that release’s inode through a hard link. Changed files use independent copies. Unsupported hard links fall back to copies. The workspace never shares writable file inodes with published releases.

Publication renames the complete staging directory into its retained release path before switching current. Deleted workspace paths remain absent from the new release. A failed stage preserves the current site and historical releases. This guarantee covers atomic visibility, not full power-loss durability. Linked files retain the previous release’s modification time.

Logs report linked_files, copied_files, copied_bytes, and compared_bytes. A bounded pool processes up to eight files concurrently. Each worker owns its comparison buffers. Publication waits for all workers before exposing a release. Independent copies retain per-file synchronization.

Direct byte comparisons still read unchanged output. They avoid copying those bytes onto replicated storage. The first publication needs independent copies when no baseline exists, and requires space for both the workspace and release.

Use mode: hostPath and set workspace.hostPath.path when you want a specific node-local disk instead of the pod’s ephemeral storage. Keep workDir underneath mountPath; the CLI also rejects filesystem roots, the source tree, and the release root as explicit --work-dir values because the workspace can be deleted and recreated when it needs a fresh seed.

Keep builderAdmin.fast at false when queued builds publish the live site. In this repo, --fast is an authoring optimization, not a production-equivalent build mode: it skips blogroll, mentions, and other expensive work that can affect user-facing output. Enable it only when the admin service is being used as a preview loop and a separate full build path still exists for public releases.

Current chart defaults also prefer clean rolling cutover instead of stop-then-start replacement. Builder-admin keeps one active leader for queue draining, file watching, refresh scheduling, and release promotion while standby pods stay ready during rollout handoff.

Match the Site Theme #

Builder admin reads the site’s configured palette from the source directory and uses its fallback mode for the operator UI. For example, this site configuration gives the admin UI the Everforest Dark colors:

[markata-go.theme]
palette = "everforest-dark"

When your site config uses palette_light, palette_dark, or fallback_mode, builder admin uses the same fallback palette. Keep the site config and any custom palette files under the mounted source directory. If the palette cannot be loaded, builder admin remains available with its default colors. Builder Admin and local Serve share a semantic browser token stylesheet for these colors and keyboard focus treatment; their page structure and production/local capabilities remain separate while a shared shell is developed.

Read Build History Quickly #

Jobs and releases are expandable: select a row to see full IDs, timings, logs, and the build record link without losing your place in the list. Release rows use their creation time as the primary label; full IDs remain available in the expanded view.

For successful builds, the duration bar compares each build with up to 60 builds completed in the last 30 days. It marks the mean and recorded maximum. Builder admin needs at least eight matching builds before it flags unusually fast or slow work, using a median/MAD baseline so a single slow build does not distort the result.

Secure Access with ForwardAuth #

Builder admin is an operator control plane. Expose it only through its protected Traefik ingress; direct Service access and kubectl port-forward fail closed because they cannot prove that the request came through the trusted proxy.

builderAdmin:
  enabled: true
  auth:
    # CIDR used by the Traefik instances and builder-admin peers that forward this
    # Ingress. 0.0.0.0/0 and ::/0 are rejected.
    trustedProxyCIDRs:
      - 10.42.0.0/24
  ingress:
    enabled: true
    host: builder.example.com
    ingressClassName: traefik
    tls:
      enabled: true
      secretName: builder-example-com-tls
    auth:
      enabled: true
      # Traefik uses this direct Service URL for ForwardAuth. The chart appends
      # /api/v1/forward-auth.
      internalUrl: http://hlab-auth.hlab-auth.svc.cluster.local:8000
      # Optional: browser-reachable auth origin for the operator's own picture.
      # This does not alter hlab-auth login, session, or WebAuthn configuration.
      publicAuthOrigin: https://auth.wayl.one
  networkPolicy:
    enabled: true
    # Verify these against the live Traefik installation before applying.
    traefikNamespace: kube-system
    traefikNamespaceSelector:
      kubernetes.io/metadata.name: kube-system
    traefikPodSelector:
      app.kubernetes.io/name: traefik
      app.kubernetes.io/instance: traefik-kube-system

The chart strips every configured identity header before calling the ForwardAuth service. On a successful decision, Traefik forwards only configured response headers to builder admin. The ForwardAuth internalUrl must use HTTPS or a cluster-local Service URL in the form http://<service>.<namespace>.svc.cluster.local:<port>; Helm rejects other HTTP URLs. Keep publicAuthOrigin on the browser-facing HTTPS auth origin when you use profile pictures. Set trustedProxyCIDRs to only the actual Traefik source CIDRs seen by the pod. A shared Pod CIDR is permitted only when it is needed for builder-admin peer forwarding and the required selector NetworkPolicy restricts that CIDR to the configured Traefik pods and builder-admin peers. Do not use universal, loopback, or link-local CIDRs; the service rejects them.

The default values use hlab-auth’s /api/v1/forward-auth endpoint, X-Hlab-* headers, and the __Host-hlab-app-session cookie. Builder admin itself has no hlab-auth API dependency: any SSO that supports Traefik ForwardAuth can be used by setting the endpoint path, response cookies, and identity-header mapping. Builder admin makes no authorization decision from a username, display name, group, role, or scope; the ForwardAuth service is the access decision point.

Authentik example #

Authentik’s proxy outpost supplies durable X-Authentik-Uid values. Configure its Traefik ForwardAuth endpoint, then map those headers in the chart:

builderAdmin:
  auth:
    headers:
      userID: X-Authentik-Uid
      username: X-Authentik-Username
      displayName: X-Authentik-Name
      email: X-Authentik-Email
      groups: X-Authentik-Groups
      roles: ""
      scopes: ""
  ingress:
    auth:
      internalUrl: http://ak-outpost.authentik.svc.cluster.local:9000
      forwardAuthPath: /outpost.goauthentik.io/auth/traefik
      responseCookies: []

For a non-Helm deployment, use the same names with builder-admin flags such as --auth-user-id-header=X-Authentik-Uid. Configure Traefik to strip every configured identity header before ForwardAuth and forward the same headers from its successful response. Do not map a mutable username to userID; use the SSO’s stable subject or UID header.

You can keep this mapping in the site configuration instead of repeating CLI flags:

[markata-go.builder_admin.auth.headers]
user_id = "X-Authentik-Uid"
username = "X-Authentik-Username"
display_name = "X-Authentik-Name"
email = "X-Authentik-Email"
groups = "X-Authentik-Groups"
roles = ""
scopes = ""

Environment variables override this file, for example MARKATA_GO_BUILDER_ADMIN_AUTH_HEADERS_USER_ID=X-Authentik-Uid. Explicit CLI flags have the highest precedence. Empty optional header values disable those display-only assertions; the durable user_id header is always required.

The operator panel uses the trusted durable user ID and any supplied profile headers only for identity display; they never grant access. Set publicAuthOrigin only when the browser can reach hlab-auth at that HTTPS origin and you want the panel to request the signed-in operator’s own picture. The URL is derived from the authenticated stable user ID; a No image fallback remains visible when it is unset, unavailable, or cannot load. Do not use this setting to change hlab-auth’s primary public auth origin, cookies/sessions, or primary WebAuthn RP.

Agent API #

Builder admin exposes a machine API at /api/v1/ for reading state and logs, inspecting build and refresh operations, enqueueing builds and refreshes, and rolling back releases. Successful mutations return HTTP 202 with an operation ID and queued status. Poll the operation detail endpoint or /api/v1/state until it completes. The API records the trusted operator ID on operations.

The API is restricted to requests that pass through ForwardAuth with a trusted bearer auth-method assertion. The default header is X-Hlab-Auth-Method; the chart strips any client-supplied copy and only accepts the value when ForwardAuth returns it. The ForwardAuth route for /api/v1/ must require the site’s operator-access scope (for example, gobuilder:access). Hlab-auth ForwardAuth validates personal bearer tokens on /api/ routes against the matched route’s required scopes and returns the identity plus auth-method headers. Deploy a hlab-auth release with bearer ForwardAuth support before enabling this API. Browser UI requests continue to use passkey sessions and CSRF validation.

Use the API with the same credential used for hlab:

curl -fsS -H "Authorization: Bearer $HLAB_TOKEN" \
  https://builder.example.com/api/v1/state

curl -fsS -X POST -H "Authorization: Bearer $HLAB_TOKEN" \
  https://builder.example.com/api/v1/builds

The API also provides GET /api/v1/builds/{id}, GET /api/v1/refreshes/{id}, GET /api/v1/logs/{filename}, POST /api/v1/refresh/{task}, and POST /api/v1/releases/{release-id}/rollback. It returns JSON errors; queue saturation returns 503 with Retry-After. The browser UI remains CSRF-protected, and bearer API authentication does not grant access to the API unless ForwardAuth validates the token and returns the trusted marker.

When builderAdmin.enabled is true, Helm fails unless the protected ingress, TLS secret, ingress host/class, ForwardAuth URL, trusted proxy CIDRs, and builder-admin ingress NetworkPolicy are all configured. The service receives its CSRF public origin as exactly https://<ingress host> from the chart. Do not supply that value from request headers or alter hlab-auth’s primary RP/origin. The NetworkPolicy permits the configured builderAdmin.port only from the configured Traefik namespace/pod selectors and other builder-admin pods; confirm the default labels match the installed controller. The peer-forwarding marker is accepted only from a configured trusted CIDR; it cannot authenticate a direct request by itself.

Authenticated GET / responses set a host-only, secure, HttpOnly, strict-SameSite CSRF cookie and include its token in each mutation form. Browser mutations must present the matching token and the exact configured Origin; programmatic clients may use X-CSRF-Token instead of a form field.

What You Can See #

The UI shows:

queued and running builds
recent successful and failed builds
the trigger source for each build
per-build duration and phase timings
full raw logs
parsed markata-go performance summary lines
current live release
old releases that can be promoted back to live
refresh task history

Reading the Operator UI #

The default Jobs workspace is the primary operational view. It puts running work, queued work, and completed builds, refreshes, and rollbacks in one list. Use Enqueue Build for a manual build, then inspect its row for status, queue wait, build duration, trigger, and release.

Select Details on a build to see phase timings, changed paths, parsed performance lines, and the raw log. Release pruning runs asynchronously after publication, so a completed build can be live before old release files finish deleting; the recorded prune timing updates when cleanup completes. Raw IDs and filesystem paths are detail data rather than dashboard metrics. On narrow screens, each build and release reflows into a labeled record so operators do not need to read a clipped desktop table.

Protected Release Previews #

Each retained successful release is available at https://<site-host>/__preview/<release-id>/. The chart protects this path with the builder-admin ForwardAuth middleware, so unpromoted content is not public. Preview links expire when release retention prunes the underlying release.

The browser tab favicon also reflects live admin state so you can spot activity without keeping the tab focused:

idle when nothing is running
queued when work is waiting
build when a build or rollback is running
refresh when a refresh task is running
error when UI polling fails

The workspace tabs show one primary view at a time so build history, refresh runs, and releases do not visually stack on top of each other during tab switches. Build and release timestamps also pair the absolute RFC3339 value with a relative age label such as (5m ago).

Build Triggers #

Builder admin can enqueue builds from:

the UI
HTTP API calls
debounced file-watch events
successful refresh task runs when configured to enqueue a build
GitHub or Forgejo push webhooks

Build on Git Push #

Enable one builder-admin service for each environment. Each service owns one checked-out branch, source directory, site directory, and webhook secret. The branch defaults to main.

# markata-go.toml
[markata-go.builder_admin.webhook]
enabled = true
branch = "main"

Set the HMAC secret outside version control. Environment variables override the config file, and explicit flags override both:

export MARKATA_GO_BUILDER_ADMIN_WEBHOOK_SECRET='replace-with-a-random-secret'
markata-go builder-admin --webhook-enabled --webhook-branch main

The endpoint is https://<builder-admin-host>/webhook. In GitHub, create a repository webhook with that payload URL, set the same secret, select JSON payloads, and subscribe to Push events. Forgejo uses the same URL and secret; select its push event. Builder admin accepts GitHub’s X-Hub-Signature-256 and Forgejo’s X-Gitea-Signature headers. Invalid signatures, events other than push, and pushes to another branch are ignored or rejected without running a build.

For an accepted matching push, builder admin runs git -C <source-dir> pull --ff-only origin <branch>. It queues a build only when that changes the checkout. Ensure the deployed source directory is a clean clone with an authenticated origin remote and that its checked-out branch tracks the configured branch. The normal source watcher remains active during the pull so a local author edit is never ignored. That safety measure can produce a follow-up file-watch build after a push.

Helm setup #

The chart exposes /webhook without the operator ForwardAuth middleware; HMAC validation protects that endpoint. Create a Kubernetes Secret, then reference it in the environment’s Helm values:

builderAdmin:
  webhook:
    enabled: true
    branch: main
    existingSecretName: builder-webhook
    existingSecretKey: webhook-secret

For a public GitHub repository, the chart can initialize the source PVC as a shallow checkout before Builder Admin starts. It refreshes that checkout on pod startup; signed push webhooks keep it current between restarts:

builderAdmin:
  sourceGit:
    enabled: true
    repository: https://github.com/WaylonWalker/markata.git
    branch: main
    depth: 1
  webhook:
    enabled: true
    branch: main
    existingSecretName: markata-docs-builder-webhook
    existingSecretKey: webhook-secret

sourceGit only seeds an empty source directory or refreshes an existing Git checkout. If the directory contains files but no .git repository, startup fails without deleting those files. The webhook continues to use a fast-forward-only pull and queues a build only when the checkout changes. Configure the builder’s site config with search.configPath when the source repository uses a non-default config filename.

Create separate releases for main, dev, and qa when they publish different domains. Give each release a distinct source checkout, site storage, builder-admin ingress host, and webhook secret. Point each repository webhook at its matching builder-admin host. Do not share a production webhook secret with preview environments.

If GitHub or Forgejo reports a successful delivery but no build appears, verify the delivery branch, the service’s configured branch, the HMAC secret, and that git -C <source-dir> pull --ff-only origin <branch> succeeds in the builder container. A delivery for an unchanged commit intentionally does not queue a build.

Rollback #

Rollback in the first version promotes a previous rendered release by repointing the current symlink.

This is fast and keeps the release model simple, but it does not restore the historical source tree.

Scheduled Refresh Tasks #

Refresh tasks are external commands that run on an interval.

Examples:

markata-go reader update
markata-go blogroll update --force
a custom remote-asset fetch command

Use them to keep reader/blogroll data or other remote caches fresh without slowing down every normal content build.

Retaining a warm workspace #

Successful publication retains the completed workspace on both same-filesystem and cross-filesystem layouts. Builder Admin reuses it only when its successful-release marker matches current. Logs report reusing build work from current release. Failed or interrupted builds and rollbacks trigger a fresh independent seed. A persistent workspace survives pod restarts. An emptyDir survives container restarts but disappears with the pod. Incremental publication still compares unchanged bytes, so storage and host load affect elapsed time.

Background release cleanup #

Builder Admin first removes obsolete releases from the published release list with an atomic rename, then deletes their files in the background. Large cleanup jobs do not hold the lock needed for promotion or rollback. Internal .pruning- directories are not rollback targets; interrupted cleanup is retried on the next prune run. Published build success is separate from cleanup errors, which appear in service logs.

Successful build but nginx returns 403 #

If nginx reports current/index.html is forbidden (13: Permission denied), inspect the completed release root permissions. Builder-admin publishes release roots as 0755 so nginx can traverse them. Older cross-filesystem publication could retain a private 0700 staging directory, and subsequent seeded builds could inherit it. Upgrade the engine and correct affected retained release roots to 0755; child file permissions do not need a recursive change for this defect.

Warm publication digest cache #

Builder Admin stores a private SHA-256 manifest beside its mutable workspace. On Linux, unchanged file identity and change timestamps allow cached digest reuse. Files with recent or changed timestamps require content hashing. Missing or corrupt cache records fall back to hashing. Other platforms always hash source files.

The manifest binds the workspace and previous release. Published releases must stay immutable. Do not edit retained releases in place. Delete the workspace’s .publication.json sibling to force content verification on the next publication. Manifest write failures leave publication usable but disable cache reuse. Logs report cached_source_hashes, cached_release_hashes, and manifest_saved. The manifest contains file identities and digests and never appears in a release.

Revision provenance and new-build status #

Builder Admin shows the running Builder executable revision beside the revision used by the latest successful build, as well as the current site Git HEAD. Its top status banner highlights New Builder revision has not built yet when the running commit differs from every retained successful build (and there is reliable previous-build provenance). A queued or running build shows a pending state. Once a successful build using that Builder revision is recorded the warning clears.

New build records persist builder_version, builder_commit, and source_commit. These are visible in Jobs details, build detail pages and the authenticated /api/v1/state response under revision. Retained releases also show recorded revisions where available. Older build records may lack these fields; the current release’s diagnostics artifact provides a best-effort fallback. Unknown revision identity is explicitly reported as unknown, not mistaken for an unbuilt revision.

Source revision comparison is Git HEAD based. Uncommitted edits can require a rebuild even if HEAD matches; this status does not claim to fingerprint dirty source files. The displayed Builder revision is taken from the running binary’s build metadata, not the site’s Git HEAD or a mutable image tag.

Web Awesome Components

2026-04-28T00:00:00Z

markata-go can render Web Awesome components from Markdown. The built-in shortcuts focus on content patterns that make sense for blogs and docs: comparisons, expandable details, tabs, copy buttons, QR codes, badges, tags, tooltips, carousels, and animated images.

Demo #

Compare the same generated graphic before and after a color treatment.

Theme Integration #

Web Awesome components inherit markata-go theme variables for text, surfaces, borders, radii, shadows, and semantic colors. This keeps component chrome aligned with the active palette instead of falling back to Web Awesome defaults.

Asset Loading #

Web Awesome uses vendored assets by default (source = "vendor"). In that mode, markata-go downloads the Web Awesome npm archive, extracts the browser-ready dist-cdn subtree, and serves it from /assets/vendor/webawesome/.

markata-go assets download includes this archive in the default asset cache, so builder images can pre-seed Web Awesome and run with MARKATA_GO_OFFLINE=true without reaching the npm registry during a site build.

Markdown #

Comparison #

Write a wa-comparison container with two images. Author them in natural left-to-right order: the first image starts on the left side of the divider and the second image starts on the right.

::: wa-comparison {position=42 caption="Compare the same graphic before and after a color treatment."}
![Before: grayscale graphic](/images/graphic-before.webp)
![After: colorful graphic](/images/graphic-after.webp)
:::

Details #

Use details for FAQs, spoilers, and advanced notes.

Self-host Web Awesome when your site must build without external CDN dependencies or when your privacy policy avoids third-party asset requests.

::: wa-details {summary="When should I self-host assets?"}
Self-host Web Awesome when your site must build without external CDN dependencies.
:::

Tabs #

Use tabs for platform-specific install instructions or examples in multiple languages.

macOS

Linux

brew install markata-go

curl -fsSL https://example.com/install.sh | sh

::: wa-tabs

:::: wa-tab {label="macOS"}
```bash
brew install markata-go
```
::::

:::: wa-tab {label="Linux"}
```bash
curl -fsSL https://example.com/install.sh | sh
```
::::
:::

Copy Button #

Use copy buttons next to commands, URLs, or config snippets.

::: wa-copy
`go test ./...`
:::

QR Code #

Use QR codes for shareable article URLs, event links, or contact links.

::: wa-qr
https://example.com/docs/guides/webawesome/
:::

Badge And Tag #

Use badges and tags for compact labels like new, stable, deprecated, or experimental.

New

Stable

::: wa-badge {variant="brand"}
New
:::

::: wa-tag {variant="success"}
Stable
:::

Tooltip #

Use tooltips for short inline explanations.

SSG

Static Site Generator

::: wa-tooltip {content="Static Site Generator"}
SSG
:::

Carousel #

Use carousels for screenshot galleries or visual changelogs.

::: wa-carousel {navigation="true" pagination="true"}
![First screenshot](/images/one.webp)
First screenshot caption
![Second screenshot](/images/two.webp)
Second screenshot caption
:::

Animated Image #

Use animated images to give readers play and pause controls for GIF or animated WebP content.

::: wa-animated-image
![Animated demo](/images/demo.gif)
:::

The longer ::: webawesome comparison form remains supported as an alias, but wa-* is the recommended authoring style. You can combine Web Awesome container classes with layout or utility classes; for example, a rendered container with class="not-prose wa-carousel" is still detected and converted.

::: webawesome comparison {position=65}
![Before](/images/before.webp)
![After](/images/after.webp)
:::

Configuration #

Enable the plugin in your hooks list. The default source is "vendor", which downloads and self-hosts Web Awesome through the shared [markata-go.assets] pipeline.

[markata-go]
hooks = ["default", "webawesome"]

[markata-go.webawesome]
enabled = true
source = "vendor"
version = "3.5.0"
output_dir = "assets/vendor/webawesome"
theme = "default"
palette = "default"
brand = "blue"

When source = "vendor", Web Awesome is downloaded into the shared assets cache ([markata-go.assets].cache_dir) and published under the shared vendor root ([markata-go.assets].output_dir). The plugin’s output_dir remains assets/vendor/webawesome by default so pages load /assets/vendor/webawesome/... URLs.

If you prefer to load assets from a CDN instead of self-hosting, set source = "cdn":

[markata-go.webawesome]
source = "cdn"
version = "3.5.0"
# cdn_base_url defaults to https://cdn.jsdelivr.net/npm/@awesome.me/webawesome@<version>/dist-cdn

Self-hosting (the default) is recommended when your site must build without external CDN dependencies, when your privacy policy avoids third-party asset requests, or when you want stable, immutable component versions tied to your repo. You can prefetch the shared asset cache with markata-go assets download.

Raw Components #

Raw Web Awesome HTML works too. Any page containing a <wa-*> element automatically gets the configured Web Awesome assets.

<wa-callout variant="brand">Raw Web Awesome also works.</wa-callout>

Raw Web Awesome also works.

Component Loading #

Pages that use any wa-* element automatically get the Web Awesome stylesheet and initialized Web Awesome autoloader. The built-in template imports webawesome.loader.js, sets the configured base path, and calls startLoader() so the autoloader watches the document for <wa-*> tags and lazy-imports the matching component modules on demand. Each page only downloads what it actually uses. Pages without wa-* elements do not load Web Awesome CSS or JavaScript.

When source = "vendor", the theme stylesheet and autoloader are served from your site under output_dir (for example /assets/vendor/webawesome/styles/themes/default.css and /assets/vendor/webawesome/webawesome.loader.js). The focused theme stylesheet avoids Web Awesome’s global native-element styles so normal site typography and link styling stay unchanged. These files come from the npm tarball downloaded through the shared [markata-go.assets] cache/output pipeline. When source = "cdn", they are served from the browser-ready https://cdn.jsdelivr.net/npm/@awesome.me/webawesome@VERSION/dist-cdn/ subtree.

Python Source Docs

2026-04-13T00:00:00Z

Use the optional python_docs plugin to turn Python modules into source-backed documentation pages.

The plugin only runs when it is explicitly listed in hooks and enabled in its config section.

Example #

[markata-go]
hooks = ["default", "python_docs"]

[markata-go.python_docs]
enabled = true
patterns = ["src/**/*.py", "pkg/**/*.py"]
exclude = ["**/tests/**", "**/.venv/**"]
slug_prefix = "api"
template = "docs"
include_source = true
include_module_code = false
published = false

This creates one generated post per discovered Python module.

Examples:

pkg/util.py -> /api/pkg/util/
pkg/client/http.py -> /api/pkg/client/http/
pkg/__init__.py -> /api/pkg/

What Gets Rendered #

For each module, the plugin generates markdown that includes:

the module name and source path
the module docstring rendered as markdown
an imports section
an API index for classes and functions
per-symbol sections with signatures and docstrings
collapsible source snippets without repeated leading docstrings

Cross-Linking #

When multiple modules are documented together, the plugin links internal references where possible.

Supported cases include:

import lists like from pkg.util import greet
backticked references like `pkg.util`
Sphinx-style refs like :func:pkg.util.greet``

Common Options #

[markata-go]
hooks = ["default", "python_docs"]

[markata-go.python_docs]
enabled = true
patterns = ["src/**/*.py"]
directories = ["pkg", "scripts"]
exclude = ["**/tests/**"]
use_gitignore = true
slug_prefix = "reference"
template = "docs"
published = false
include_private = false
include_source = true
include_module_code = false
tags = ["python", "docs"]
interpreter = "python3"

Notes #

The plugin requires a Python interpreter on PATH.
The plugin must be listed in [markata-go].hooks as python_docs.
Markdown content loading is unchanged; Python docs are added alongside normal posts.
Generated docs are unpublished by default so they stay out of feeds and sitemap unless you opt in.

AI Agent Prompt Templates

2026-03-12T00:00:00Z

markata-go includes reusable GPT-5.4 prompt templates for OpenCode workflows. Use the generator script to fetch issue metadata from GitHub and render prompt files for either a single issue or a group of issues.

Files #

continue-prompt-gpt-54.template.txt - multi-issue template
continue-prompt-gpt-54-single-issue.template.txt - single-issue template
scripts/fill_continue_prompts.py - generator script

Generate Prompt Files #

Generate a multi-issue prompt and one single-issue prompt:

python scripts/fill_continue_prompts.py 942

Generate a multi-issue prompt for several issues plus one single-issue prompt per issue:

python scripts/fill_continue_prompts.py 935 936 937 938 939

Write the rendered content back to the root prompt filenames too:

python scripts/fill_continue_prompts.py 942 --write-root-prompts

Options #

Use a different worktree root hint:

python scripts/fill_continue_prompts.py 942 --worktree-root ../worktrees

Write outputs to a different directory:

python scripts/fill_continue_prompts.py 942 --output-dir /tmp/prompts

Use a different repository:

python scripts/fill_continue_prompts.py 942 --repo owner/repo

Output Naming #

For issue 942, the script writes:

continue-prompt-gpt-54-issues-942.txt
continue-prompt-gpt-54-issue-942.txt

For issues 935 936 937, the script writes:

continue-prompt-gpt-54-issues-935-936-937.txt
continue-prompt-gpt-54-issue-935.txt
continue-prompt-gpt-54-issue-936.txt
continue-prompt-gpt-54-issue-937.txt

Notes #

The script requires the GitHub CLI and access to the target repository.
Single-issue prompts include a suggested branch name and worktree path hint.
The templates stay editable as plain text, so prompt tuning does not require Python changes.

CLI List Command Design

2026-02-16T00:00:00Z

Goal #

Add a list command with posts, tags, and feeds subcommands for fast, scriptable data exploration. Output must support a Unix-friendly path-only format for piping.

Command Shape #

markata-go list posts
markata-go list tags
markata-go list feeds

Shared flags:

--format (table default, json, csv, path)
--sort
--order (asc or desc, default desc)
--filter (posts only, passed to filter expression engine)

Output Formats #

table: fixed-width ASCII table with headers, no color
json: array of objects with raw values
csv: header row + values, same column order as table
path: one value per line, optimized for piping

Path format fields:

posts: path
tags: name
feeds: path (fallback to name if missing)

Cache #

Cache file: .markata/cache/list.json
Reused when config hash matches and file metadata is unchanged
Partial refresh re-parses only changed files and rebuilds tags/feeds from cached posts

Data Sources #

Use services.App and Build.LoadForTUI for consistent stats and feed data.
Posts: Posts.List with ListOptions for sort/filter.
Tags: Tags.List, sorted in CLI when custom sort requested.
Feeds: Feeds.List, sorted in CLI when custom sort requested.

Sorting #

Posts: date, title, words, path, reading_time, tags (service-level).

Tags: name, count, words, reading_time.

Feeds: name, posts, words, reading_time, avg_reading_time.

Errors #

Invalid format/sort/order: print a clear error and exit code 1.
Load errors: return the underlying error.

Docs + Spec #

New spec file for list behavior.
Update CLI reference and add a short guide with examples.

Data Exploration

2026-02-16T00:00:00Z

Use list for scriptable output and tui for interactive browsing.

List Posts #

# Default table output
markata-go list posts

# Path-only output for piping
markata-go list posts --format path

# Filter posts with an expression
markata-go list posts --filter "published == true and 'go' in tags"

# Sort by title, ascending
markata-go list posts --sort title --order asc

# List posts for a feed
markata-go list posts --feed blog

# Table output
markata-go list tags

# JSON output for scripts
markata-go list tags --format json

List Feeds #

# Table output
markata-go list feeds

# CSV output for spreadsheets
markata-go list feeds --format csv

# List posts for a feed
markata-go list feeds posts blog

# List post paths for a feed
markata-go list feeds posts blog --format path

Path-Only Output #

The path format prints one value per line for easy piping:

# Open each post in your editor
markata-go list posts --format path | xargs -n 1 $EDITOR

# Create a tag list file
markata-go list tags --format path > tags.txt

When --site-dir or MARKATA_GO_SITE_DIR selects a site, post paths are absolute. This lets agents and scripts edit results from any directory:

markata-go --site-dir ~/sites/blog search "configuration" --format path
# Edit the returned Markdown path directly.

Interactive Browsing #

For a full-screen view with filtering and sorting:

markata-go tui

Cache #

list and tui use a persistent cache at .markata/cache/list.json. It updates automatically when files change. Delete the file to force a full refresh.

Image Optimization Plugin Design

2026-02-15T00:00:00Z

Goal #

Add an optional image_optimization plugin that generates AVIF/WebP variants for local images at build time and rewrites HTML to use <picture> with a stable <img> fallback. External images are unchanged.

Constraints #

Use external CLI encoders (avifenc, cwebp) when available.
Do not fail the build if an encoder is missing; warn and skip the format.
Do not add responsive sizes in this issue.
Write optimized variants next to the original output image.

User Configuration #

[markata-go]
hooks = ["default", "image_optimization"]

[markata-go.image_optimization]
enabled = true
formats = ["avif", "webp"]
quality = 80
avif_quality = 80
webp_quality = 80
cache_dir = ".markata/image-cache"
avifenc_path = ""
cwebp_path = ""

Behavior #

Render stage scans post.ArticleHTML for <img> tags.
For local src values, rewrite each to a <picture> wrapper:
- <source type="image/avif" srcset="..."> when AVIF is enabled
- <source type="image/webp" srcset="..."> when WebP is enabled
- Keep the original <img> as the fallback
External URLs, protocol-relative URLs, and data URIs are skipped.

Outputs #

image.jpg -> image.avif and image.webp in the same output folder.
Original image remains unchanged and serves as the fallback.

Cache Strategy #

Cache metadata in .markata/image-cache/ keyed by:

Source path
File size + mod time
Encoder + quality settings

If the key matches, skip re-encoding.

Error Handling #

Missing encoder: warn once per build; skip that format.
Encode failure: warn for that file; keep original <img>.
Missing source file: warn and skip.

Tests #

HTML rewrite: local images get <picture>, external images stay unchanged.
Cache hit skips encode; cache miss re-encodes.
Missing encoder does not fail build.
Failed encode does not corrupt output HTML.

Docs and Spec #

Add image_optimization to spec/spec/OPTIONAL_PLUGINS.md.
Document config and usage in docs/guides/configuration.md and docs/reference/plugins.md.
Add a new user guide in docs/guides/image-optimization.md.

CI/Builder Image #

Add avifenc and cwebp to the builder image in PR #781.

Image Optimization

2026-02-15T00:00:00Z

The image_optimization plugin generates AVIF and WebP variants for local images and rewrites HTML to use a <picture> element with the original image as the fallback.

Quick Start #

Enable the plugin in your hooks:

[markata-go]
hooks = ["default", "image_optimization"]

[markata-go.image_optimization]
enabled = true

Requirements #

avifenc for AVIF output
cwebp for WebP output

If a tool is missing, the build continues and that format is skipped.

Example Output #

Input HTML:

<img src="/images/cat.jpg" alt="Cat">

Output HTML:

<picture>
  <source type="image/avif" srcset="/images/cat-480w.avif 480w, /images/cat-960w.avif 960w" sizes="100vw">
  <source type="image/webp" srcset="/images/cat-480w.webp 480w, /images/cat-960w.webp 960w" sizes="100vw">
  <img src="/images/cat.jpg" alt="Cat">
</picture>

The generated .avif and .webp files are written next to the original image in the output folder.

The optimizer reuses the image cache in .markata/image-cache and skips re-encoding unchanged inputs across rebuilds. Each build logs a summary of targets, missing sources, variants checked, cache hits and misses, and encoder calls and failures. This makes cache reuse distinguishable from actual image work.

Configuration #

[markata-go.image_optimization]
enabled = true
formats = ["avif", "webp"]
quality = 80
avif_quality = 80
webp_quality = 80
widths = [480, 960]
sizes = "100vw"
cache_dir = ".markata/image-cache"
avifenc_path = ""
cwebp_path = ""

Notes #

Only local images are processed (relative paths and site-root paths).
External URLs, protocol-relative URLs, and data URIs are skipped.
Images already inside <picture> are left unchanged.

For full details, see the plugin reference.

Multi-Author Support

2026-02-12T00:00:00Z

Markata-go supports multiple authors with rich metadata including roles, bios, avatars, and social links. This guide covers how to configure authors and reference them in your posts.

Quick Start #

1. Configure Authors #

Add authors to your markata-go.toml:

[markata-go.authors]

[markata-go.authors.authors.waylon]
name = "Waylon Walker"
role = "author"
url = "https://waylonwalker.com"
avatar = "/images/waylon.jpg"
bio = "Python and Go developer"
active = true
default = true

[markata-go.authors.authors.guest]
name = "Guest Writer"
role = "editor"
bio = "Occasional contributor"
guest = true
active = true

2. Reference Authors in Posts #

---
title: My Post
authors:
  - waylon
  - guest
---

Author Configuration #

Author Fields #

Field	Type	Description
`name`	string	Required - Display name
`role`	string	Simple role label (author, editor, etc.)
`bio`	string	Short biography
`avatar`	string	Avatar image URL or path
`url`	string	Personal website URL
`email`	string	Contact email
`social`	map	Social media links
`default`	bool	Default author for posts without explicit authors
`guest`	bool	Guest author flag
`active`	bool	Whether author is currently active

Default Author #

Set default = true on one author. Posts without an explicit authors frontmatter field will automatically use this author:

[markata-go.authors.authors.waylon]
name = "Waylon Walker"
default = true

Author Pages #

Generate individual author profile pages:

[markata-go.authors]
generate_pages = true
url_pattern = "/authors/{id}/"

Frontmatter #

Simple Format #

Reference authors by ID:

---
title: My Post
authors:
  - waylon
  - guest
---

Extended Format #

Specify per-post roles and details:

---
title: Collaborative Post
authors:
  - id: waylon
    role: author
    details: wrote the introduction
  - id: codex
    role: pair programmer
    details: wrote the code examples
---

Key Aliases #

Use convenient aliases for common keys:

---
authors:
  - name: waylon     # same as id: waylon
    title: author    # same as role: author
    description: wrote it  # same as details: ...
---

Legacy Format #

The older single-author format still works:

---
title: My Post
author: waylon
---

Template Access #

In templates, access author data:

{% for author in post.author_objects %}
  <span>{{ author.name }}</span>
  {% if author.role %}({{ author.role }}){% endif %}
{% endfor %}

Available author properties:

id, name, bio, email, avatar, url
role - Simple role label
role_display - Pre-computed display string
guest, active, default
social - Map of platform -> URL
contributions - CReDiT taxonomy roles
details - Per-post contribution details

Role System #

Simple Roles #

Use the role field for blog-friendly roles:

[markata-go.authors.authors.waylon]
name = "Waylon Walker"
role = "author"

Common roles: author, editor, reviewer, photographer, illustrator, translator

CReDiT Roles #

For academic-style contribution tracking, use contributions:

[markata-go.authors.authors.waylon]
name = "Waylon Walker"
contributions = ["Conceptualization", "Software", "Writing"]

Examples #

Multiple Authors with Different Roles #

---
title: Building a CLI Tool
authors:
  - id: waylon
    role: author
    details: wrote the core implementation
  - id: kimmi
    role: reviewer
    details: reviewed and tested
---

Mixed Author Types #

---
title: Guest Post
authors:
  - waylon  # uses default role from config
  - id: guest-writer
    role: guest author
    details: wrote this guest post
---

Editorial credits and revision history #

The default byline keeps writers prominent and groups editing/reviewing roles below them. The first editor is displayed by name; additional editors are stacked behind a disclosure with all contributor names and roles.

Use Editorial history to show recorded reviews, GitHub file diffs, and lazily loaded inline source changes. Humans and agents can use the editorial authoring commands to commit selected edits and record their attribution automatically.

Link Avatars

2026-02-09T00:00:00Z

The link_avatars plugin automatically adds small favicon icons next to external links in your content. This helps readers quickly identify link destinations before clicking.

Quick Start #

Enable link avatars with minimal configuration:

[markata-go.link_avatars]
enabled = true

This will add a 16x16 pixel favicon icon before each external link using DuckDuckGo’s icon service.

How It Works #

The plugin supports three modes:

js (default): client-side enhancement with runtime favicon fetch
local: build-time caching, HTML points to site-relative icon URLs
hosted: build-time caching, HTML points to a hosted base URL (CDN)

In all modes, the plugin applies the same ignore rules and uses the same CSS for sizing and positioning.

Configuration #

Basic Options #

[markata-go.link_avatars]
enabled = true

# CSS selector for links to enhance (default: "a[href^='http']")
selector = "a[href^='http']"

# Avatar size in pixels (default: 16)
size = 16

# Position: "before" or "after" the link text (default: "before")
position = "before"

# Mode: "js", "local", or "hosted" (default: "js")
mode = "js"

# Hosted base URL for mode = "hosted"
# hosted_base_url = "https://cdn.example.com/markata/link-avatars"

Service Selection #

Choose your favicon service provider:

[markata-go.link_avatars]
enabled = true

# Options: "duckduckgo", "google", "custom"
service = "duckduckgo"

Service	URL Template	Notes
`duckduckgo`	`icons.duckduckgo.com/ip3/{host}.ico`	Default, privacy-focused
`google`	`google.com/s2/favicons?domain={host}`	Reliable, supports size param
`custom`	User-provided template	For self-hosted services

Custom Template #

Use a custom favicon service:

[markata-go.link_avatars]
enabled = true
service = "custom"
template = "https://favicon.splitbee.io/?url={origin}"

Template placeholders:

{host} - Domain name (e.g., github.com)
{origin} - Full origin URL-encoded (e.g., https%3A%2F%2Fgithub.com)

Ignore Rules #

Exclude specific links from getting avatars. Links that wrap images are always skipped.

[markata-go.link_avatars]
enabled = true

# Skip links to these domains
ignore_domains = ["localhost", "127.0.0.1", "example.com"]

# Skip links to these exact origins
ignore_origins = ["https://internal.example.com"]

# Skip links matching these CSS selectors
ignore_selectors = ["nav a", ".footer a", "a.plain-link"]

# Skip links with these classes
ignore_classes = ["no-avatar", "internal"]

# Skip links inside elements with these IDs
ignore_ids = ["site-nav", "footer"]

Full Configuration Example #

[markata-go.link_avatars]
enabled = true
selector = "article a[href^='http']"  # Only article links
service = "google"
size = 14
position = "after"
ignore_domains = ["localhost", "127.0.0.1"]
ignore_classes = ["no-avatar"]
ignore_selectors = ["nav a", ".sidebar a"]

CSS Customization #

The plugin adds these classes to enhanced links:

.has-avatar - Applied to all links with avatars
.has-avatar-before - Avatar appears before text
.has-avatar-after - Avatar appears after text

Override Default Styles #

/* Change avatar appearance */
a.has-avatar::before,
a.has-avatar::after {
  opacity: 0.7;
  border-radius: 2px;
  margin: 0 0.4em;
}

/* Add hover effect */
a.has-avatar:hover::before,
a.has-avatar:hover::after {
  opacity: 1;
  transform: scale(1.1);
}

/* Hide avatars in specific contexts */
.prose a.has-avatar::before,
.prose a.has-avatar::after {
  display: none;
}

Dark Mode Considerations #

The CSS handles both light and dark modes automatically. For custom styling:

/* Dark mode avatar styling */
@media (prefers-color-scheme: dark) {
  a.has-avatar::before,
  a.has-avatar::after {
    filter: brightness(1.2);
  }
}

Opt-Out Per Link #

Add the no-avatar class (or your configured ignore class) to skip specific links:

[Regular link](https://github.com) gets an avatar.

[No avatar link](https://github.com){.no-avatar} is excluded.

Or use inline HTML:

<a href="https://example.com" class="no-avatar">Plain link</a>

Performance #

The plugin is designed for minimal performance impact:

js mode: client-side, lazy favicon loading via Intersection Observer
local/hosted modes: build-time caching, no runtime JS or external requests
Deterministic builds - Generated assets are stable between builds

Generated Files #

When enabled, the plugin creates:

output/
├── css/
│   └── link-avatars.css  # Styling
├── js/
│   └── link-avatars.js   # Client-side JavaScript (js mode only)
└── assets/
    └── markata/
        └── link-avatars/     # Cached icons (local/hosted modes)
            └── example.com.ico

These are automatically included in your page’s <head>.

Troubleshooting #

Favicons Not Showing #

Check browser console for errors
Verify links match selector - Default is a[href^='http']
Check ignore rules - Link might match an ignore pattern
Test favicon service - Try the URL directly in browser

Favicon Service Blocked #

Some ad blockers may block favicon services. Consider:

Using a self-hosted favicon service
Adding exceptions for trusted services
Providing fallback styling

Layout Shift #

If avatars cause layout shift:

/* Reserve space for avatar */
a.has-avatar {
  padding-left: 1.5em;
  position: relative;
}

a.has-avatar::before {
  position: absolute;
  left: 0;
}

View Transitions Configuration

2026-02-02T00:00:00Z

Complete reference for configuring the View Transitions API behavior in markata-go.

Overview #

View Transitions can be configured via your markata.toml or YAML config file. All settings are optional - sensible defaults are provided.

Configuration Options #

Add a [markata-go.view_transitions] section to your config:

[markata-go.view_transitions]
enabled = true              # Enable/disable view transitions globally
debug = false               # Log debug messages to console
duration = 120              # Default transition duration in ms
update_meta = true          # Update meta tags on navigation
scroll_to_top = true        # Scroll to top on navigation (unless hash present)
skip_classes = []           # Additional CSS classes to skip
skip_selectors = []         # Additional selectors to skip

In TOML, nest this under [markata-go.view_transitions] because markata-go loads site config from the top-level [markata-go] table.

Quick Examples #

TOML (`markata.toml`) #

[markata-go.view_transitions]
enabled = true
debug = false
duration = 120
update_meta = true
scroll_to_top = true
skip_classes = ["no-transition", "external-link"]
skip_selectors = ["[data-skip-transition]", ".modal a"]

YAML (`markata.yaml`) #

markata-go:
  view_transitions:
    enabled: true
    debug: false
    duration: 120
    update_meta: true
    scroll_to_top: true
    skip_classes:
      - no-transition
      - external-link
    skip_selectors:
      - "[data-skip-transition]"
      - ".modal a"

Option Reference #

`enabled` #

Type: Boolean
Default: true

Enable or disable view transitions globally.

[markata-go.view_transitions]
enabled = false  # Disable view transitions completely

When disabled, all navigation uses standard browser behavior (no transitions).

Use case: Temporarily disable for testing or performance debugging.

`debug` #

Type: Boolean
Default: false

Enable debug logging to browser console.

[markata-go.view_transitions]
debug = true

Console output when enabled:

View Transitions API initialized
Starting view transition to: /blog/my-post/
Prefetching URL: /blog/next-post/
\[view-transitions\] timing { fetchMs: 18.4, parseMs: 4.2, swapMs: 7.3, reinitMs: 5.1, totalMs: 42.6 }
View transition completed
Skipping link with class: no-transition

Useful for:

Debugging transition issues
Seeing which links are being intercepted
Inspecting fetch/parse/swap/reinit timing in the browser console
Understanding why certain links are skipped

`duration` #

Type: Integer (milliseconds)
Default: 120

Default transition duration in milliseconds. Used as a reference value.

[markata-go.view_transitions]
duration = 220  # Slower transitions

Note: The actual animation duration is controlled by CSS:

::view-transition-old(main-content),
::view-transition-new(main-content) {
  animation-duration: 0.5s;  /* Match config.duration / 1000 */
}

`update_meta` #

Type: Boolean
Default: true

Update meta tags (description, Open Graph, Twitter cards, canonical links) when navigating.

[view_transitions]
update_meta = false  # Skip meta tag updates

When true, updates:

<meta name="description">
<meta property="og:*"> (Open Graph tags)
<meta name="twitter:*"> (Twitter Card tags)
<link rel="canonical">

When false, only updates:

Page title
Body content

Use case: Set to false for slightly better performance if you don’t rely on meta tags changing.

`scroll_to_top` #

Type: Boolean
Default: true

Automatically scroll to top of page after navigation (unless URL has a hash).

[view_transitions]
scroll_to_top = false  # Keep scroll position

Behavior:

When true: Scrolls to top (window.scrollTo(0, 0))
If URL has hash (#section): Smooth scrolls to that element (ignores this setting)
When false: Maintains current scroll position

Use case: Set to false for documentation sites where users may want to maintain context.

`skip_classes` #

Type: Array of strings
Default: []

Additional CSS classes to skip (won’t trigger view transitions).

[view_transitions]
skip_classes = ["no-transition", "instant-nav", "legacy-link"]

Usage in HTML:

<a href="/page/" class="no-transition">Skip transition</a>
<a href="/instant/" class="instant-nav">Instant navigation</a>

Built-in skip classes (always skipped):

.toc-link - Table of Contents links (use smooth scroll instead)

`skip_selectors` #

Type: Array of strings
Default: []

Additional CSS selectors to skip using element.matches().

[view_transitions]
skip_selectors = [
  "[data-no-transition]",
  ".modal a",
  "#sidebar nav a",
  "[rel~='nofollow']"
]

Usage in HTML:

<a href="/page/" data-no-transition>No transition</a>

<div class="modal">
  <a href="/help/">Won't transition (inside modal)</a>
</div>

<nav id="sidebar">
  <a href="/nav/">Won't transition (in sidebar)</a>
</nav>

Built-in skip selectors (always skipped):

a[target="_blank"] - External links
a[download] - Download links
a[rel~="external"] - External rel links
a[hx-get], a[hx-post] - HTMX-managed links
a[data-no-transition] - Explicit opt-out

Built-in skip behavior (always skipped):

Non-HTML resources (any URL with a non-HTML file extension), including .md, .txt, .xml, .json

Common Use Cases #

Development Mode #

Enable detailed logging during development:

[view_transitions]
enabled = true
debug = true

Prevent transitions for links inside modals:

[view_transitions]
skip_selectors = [
  ".modal a",
  ".overlay a",
  "[role='dialog'] a"
]

Disable Meta Updates for Performance #

Skip meta tag updates for slightly faster transitions:

[view_transitions]
update_meta = false

Keep Scroll Position (Documentation Sites) #

Maintain scroll position when navigating docs:

[view_transitions]
scroll_to_top = false

Skip Transitions for External-Looking Links #

[view_transitions]
skip_classes = ["external", "outbound"]
skip_selectors = ["[rel~='external']", "[target='_blank']"]

Runtime Configuration #

Inspect or modify configuration at runtime via browser console:

// View current config
console.log(window.VIEW_TRANSITIONS_CONFIG);

// Temporarily disable
window.VIEW_TRANSITIONS_CONFIG.enabled = false;

// Enable debug mode
window.VIEW_TRANSITIONS_CONFIG.debug = true;

// Add skip class
window.VIEW_TRANSITIONS_CONFIG.skipClasses.push('my-class');

Note: Runtime changes only affect the current page. Reload to reset.

Per-Link Opt-Out #

Disable transitions for individual links without changing config:

<!-- Using data attribute (always works) -->
<a href="/page/" data-no-transition>No transition</a>

<!-- Using CSS class (requires config) -->
<a href="/page/" class="no-transition">No transition</a>

Disabling Temporarily #

For testing or debugging, disable in browser console:

// Option 1: Disable via config
window.VIEW_TRANSITIONS_CONFIG.enabled = false;

// Option 2: Undefine the API
document.startViewTransition = undefined;

// Option 3: Reload page
location.reload();

Default Behavior #

If you don’t add [view_transitions] to your config, these defaults apply:

[markata-go.view_transitions]
enabled = true              # View transitions ON by default
debug = false               # No console logging
duration = 120              # 120ms reference duration
update_meta = true          # Update meta tags
scroll_to_top = true        # Scroll to top on navigation
skip_classes = []           # No custom skip classes
skip_selectors = []         # No custom skip selectors

Minimal Configuration #

The simplest valid config (uses all defaults):

[view_transitions]
enabled = true

Or just omit the section entirely - view transitions are enabled by default!

Troubleshooting #

“View Transitions not working” #

Check browser support (Chrome 111+, Safari 18+, Edge 111+)
Check console for errors with debug = true
Verify enabled = true in config
Check window.VIEW_TRANSITIONS_CONFIG in console

“Specific links not transitioning” #

Check if link matches skip_selectors or skip_classes
Check if link is external (target="_blank")
Check if link has HTMX attributes (hx-get, etc.)
Enable debug = true to see why link is skipped

Enable debug = true and watch the fetchMs, parseMs, swapMs, and reinitMs timing log
Check whether the transition was prefetched (prefetched: true)
Use the browser Network tab to confirm HTML responses are served from cache when expected
Profile re-initialization listeners after view-transition-complete if reinitMs is consistently high
If swapMs is high, check whether the page is replacing more DOM than necessary

“Scripts not working after transition” #

Make sure scripts expose init functions and listen for view-transition-complete:

function init() {
  // Your initialization
}

init(); // Initial load
window.addEventListener('view-transition-complete', init); // After transitions

CSS Animation Customization #

While config controls behavior, CSS controls visual appearance:

/* Faster transitions */
::view-transition-old(main-content),
::view-transition-new(main-content) {
  animation-duration: 0.2s;
}

/* Different animation per element */
::view-transition-new(main-content) {
  animation: fade-in 0.3s, slide-up 0.3s;
}

::view-transition-new(site-nav) {
  animation: none;  /* Nav doesn't animate */
}

See [[view-transitions|View Transitions Guide]] for CSS customization examples.

[[view-transitions|View Transitions Guide]] - Main documentation
[[performance|Performance]] - Performance tips
[[configuration|Configuration]] - General markata-go configuration

Example Configurations #

Minimal (All Defaults) #

# No config needed - view transitions enabled by default

Development #

[view_transitions]
enabled = true
debug = true

Production (Performance Optimized) #

[view_transitions]
enabled = true
debug = false
update_meta = false
duration = 250

Documentation Site #

[view_transitions]
enabled = true
scroll_to_top = false
skip_selectors = [".toc a", ".sidebar a"]

With Skip Rules #

[view_transitions]
enabled = true
skip_classes = ["instant", "no-anim"]
skip_selectors = [
  ".modal a",
  "[data-external]",
  "#admin-nav a"
]

Disabled #

[view_transitions]
enabled = false

View Transitions API

2026-02-02T00:00:00Z

Smooth, animated transitions between pages and views using the modern View Transitions API. This implementation provides a polished user experience with automatic transitions for all internal navigation.

Quick Start #

View Transitions are enabled by default. No configuration required!

To customize behavior, add to your markata.toml:

[view_transitions]
enabled = true
debug = false

See [[view-transitions-config|Configuration Reference]] for all options.

What It Does #

The View Transitions API automatically adds smooth animations when users navigate between pages:

Wikilinks ([[slug]]) - Smooth transitions between related content
Card clicks - Polished navigation from feeds to full posts
Navigation links - Stable header/footer during transitions
Post navigation - Smooth prev/next post transitions
Breadcrumbs - Contextual navigation animations
All internal links - Any <a href> to same-origin pages

Smart Exclusions #

These link types are automatically skipped (use normal navigation):

External links (target="_blank")
Download links
TOC/anchor links (use smooth scroll instead)
HTMX links (handle their own updates)
Links with data-no-transition attribute

How It Works #

1. Link Interception #

A global event listener intercepts clicks on internal links:

// User clicks an internal link
document.addEventListener('click', (e) => {
  const link = e.target.closest('a');
  if (shouldTransition(link)) {
    e.preventDefault();
    // Start view transition...
  }
});

2. Content Fetching #

The new page is fetched and parsed before the transition starts so the current view stays responsive while network work happens:

const response = await fetch(url);
const html = await response.text();
const newDoc = new DOMParser().parseFromString(html, 'text/html');

3. Transition Animation #

The browser animates between old and new content:

document.startViewTransition(() => {
  // Update only the changing layout regions.
  document.querySelector('#view-transition-page').replaceWith(
    newDoc.querySelector('#view-transition-page').cloneNode(true),
  );
  document.title = newDoc.title;
  history.pushState(null, '', url);
});

4. Script Re-initialization #

After transition, page scripts are re-initialized:

// Dispatch event for scripts to listen to
window.dispatchEvent(new CustomEvent('view-transition-complete'));

// Scripts automatically re-initialize
if (window.initTooltips) window.initTooltips();
if (window.initScrollSpy) window.initScrollSpy();

Browser Support #

✅ Chrome/Edge 111+ - Full support
✅ Safari 18+ (macOS 15+, iOS 18+) - Full support
✅ Opera 97+ - Full support
⚠️ Firefox - In development

Graceful degradation: On unsupported browsers, navigation works normally without transitions.

Default Animation #

The default transition is a fade + slide-up effect:

Old content: Fades out (250ms)
New content: Fades in + slides up from 20px below (300ms)
Navigation: Stays stable (200ms minimal animation)

CSS Implementation #

/* Assign transition names */
.post-content,
.posts-list {
  view-transition-name: main-content;
}

/* Animate old content out */
::view-transition-old(main-content) {
  animation: fade-out 0.25s ease-out;
}

/* Animate new content in */
::view-transition-new(main-content) {
  animation: fade-in 0.3s ease-in, slide-up 0.3s ease-out;
}

@keyframes fade-out {
  to { opacity: 0; }
}

@keyframes fade-in {
  from { opacity: 0; }
}

@keyframes slide-up {
  from { transform: translateY(20px); }
}

Customization #

See [[view-transitions-config|Configuration Reference]] for complete customization options.

Quick Examples #

Enable debug logging:

[view_transitions]
debug = true

Skip transitions for specific classes:

[view_transitions]
skip_classes = ["instant-nav", "no-animation"]

Disable globally:

[view_transitions]
enabled = false

Per-link opt-out:

<a href="/page/" data-no-transition>Skip transition</a>

Custom CSS Animations #

Override the default animations in your custom CSS:

Different Animation Style #

/* Slide from right instead of bottom */
::view-transition-new(main-content) {
  animation: fade-in 0.3s, slide-from-right 0.3s;
}

@keyframes slide-from-right {
  from {
    opacity: 0;
    transform: translateX(30px);
  }
}

Faster Transitions #

::view-transition-old(main-content),
::view-transition-new(main-content) {
  animation-duration: 0.2s;
}

Per-Element Transitions #

/* Different animation for post titles */
.post-title {
  view-transition-name: post-title;
}

::view-transition-new(post-title) {
  animation: fade-in 0.3s, scale-up 0.3s;
}

@keyframes scale-up {
  from { transform: scale(0.95); }
}

Individual Card Morphing #

Give each card a unique transition name:

<article class="card" style="view-transition-name: card-{{ post.slug }};">
  ...
</article>

Now cards will morph smoothly when navigating!

Performance #

Bundle size: ~8KB unminified JavaScript
Overhead: Near-zero (exits early on unsupported browsers)
Animation: GPU-accelerated
Network: Uses standard fetch() API
Memory: One active navigation at a time with a small bounded prefetch cache

Performance Tips #

Keep pages small - Large HTML takes longer to parse
Optimize images - Images in new content delay transition
Minimize inline scripts - Scripts need re-initialization
Use caching - Browser caches reduce fetch time
Swap smaller regions - Replacing the page wrapper is usually cheaper than replacing the entire body
Avoid broad named snapshots - Prefer shared element names on small cards, titles, or headers rather than whole articles or sidebars

Accessibility #

View Transitions respect user preferences:

Reduced Motion #

Users who prefer reduced motion automatically get instant transitions:

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none !important;
  }
}

Screen Readers #

Page title updates immediately
Main content landmark is preserved
Focus management handled automatically
No ARIA changes needed

Troubleshooting #

Transitions Not Working #

Check browser support - Only Chrome 111+, Safari 18+, Opera 97+
Check console - Look for errors or warnings
Enable debug mode - Set debug = true in config
Verify enabled - Check window.VIEW_TRANSITIONS_CONFIG.enabled

Specific Links Not Transitioning #

External link? - Links with target="_blank" are skipped
HTMX link? - Links with hx-get are skipped
TOC link? - Anchor links use smooth scroll
Custom skip rule? - Check skip_classes and skip_selectors
Non-HTML file? - URLs like .md, .txt, .xml, .json use native browser navigation

Enable debug mode to see why links are skipped:

[view_transitions]
debug = true

Then check browser console when clicking links.

Scripts Not Working After Transition #

Make sure your custom scripts listen for the re-initialization event:

function myInit() {
  // Your initialization code
}

// Run on initial page load
myInit();

// Re-run after view transitions
window.addEventListener('view-transition-complete', myInit);

markata-go dispatches this event after the browser transition finishes. That keeps expensive script hydration out of the critical transition snapshot and makes animations less likely to stutter.

Janky Transitions #

If transitions stutter, enable debug mode and inspect the timing payload logged to the console:

[view_transitions]
debug = true

High fetchMs or parseMs points to network or page size. High swapMs points to expensive DOM/head changes. High reinitMs points to custom scripts doing too much work after navigation.

Transition Too Fast/Slow #

Adjust animation duration in CSS:

::view-transition-old(main-content),
::view-transition-new(main-content) {
  animation-duration: 0.5s; /* Slower */
}

Advanced Usage #

Transition Types #

Add custom data attributes to control transitions per-route:

// Future enhancement - not yet implemented
link.dataset.transitionType = 'slide';

Prefetching #

markata-go prefetches transition-managed links on hover/focus and can eagerly warm nearby pagination targets so [ and ] navigation feels more immediate. Prefetching is debounced and bounded to avoid excessive fetch/parse work when a user moves across a dense sidebar or feed.

Prefetched documents are reused for five seconds after they finish loading. Expired entries are evicted before the bounded cache admits new work; navigating to an older entry fetches it again with HTTP cache revalidation, so a published update can replace an older in-memory page. HTTP caches can use retained ETag and Last-Modified validators; servers that mark responses no-store may require a full response. If revalidation fails, navigation falls back to the ordinary static page request.

document.addEventListener('mouseover', (event) => {
  const link = event.target.closest('a');
  if (link) {
    window.prefetchViewTransitionUrl(link.href);
  }
});

Loading States #

Show loading indicator during fetch:

// Future enhancement - not yet implemented
document.addEventListener('htmx:beforeRequest', () => {
  showLoadingSpinner();
});

Examples #

Simple Fade #

::view-transition-old(main-content) {
  animation: fade-out 0.3s;
}

::view-transition-new(main-content) {
  animation: fade-in 0.3s;
}

Scale Transition #

::view-transition-old(main-content) {
  animation: scale-down 0.3s;
}

::view-transition-new(main-content) {
  animation: scale-up 0.3s;
}

@keyframes scale-down {
  to { transform: scale(0.95); opacity: 0; }
}

@keyframes scale-up {
  from { transform: scale(0.95); opacity: 0; }
}

Slide Transition #

::view-transition-old(main-content) {
  animation: slide-out-left 0.3s;
}

::view-transition-new(main-content) {
  animation: slide-in-right 0.3s;
}

@keyframes slide-out-left {
  to { transform: translateX(-100%); opacity: 0; }
}

@keyframes slide-in-right {
  from { transform: translateX(100%); opacity: 0; }
}

[[view-transitions-config|Configuration Reference]] - All configuration options
[[performance|Performance]] - Performance optimization guide
[[keyboard-navigation|Keyboard Navigation]] - Accessibility features
[[themes|Themes]] - Customizing appearance

Resources #

Implementation Files #

JavaScript: pkg/themes/default/static/js/view-transitions.js
CSS: pkg/themes/default/static/css/components.css
Template: pkg/themes/default/templates/base.html

Troubleshooting Build Inconsistencies

2026-01-30T00:00:00Z

If you’re getting different build results on different machines, follow this diagnostic guide.

Quick Fix #

On the machine with issues, run:

cd ~/git/markata-go  # or your repo location
./scripts/clean-rebuild.sh
markata-go build --clean

Root Causes #

1. Go Build Cache (Most Common) #

Problem: Templates are embedded into the binary at compile time via //go:embed. Go’s build cache can serve stale compiled objects even after template files change.

Symptoms:

Old templates appear in output
Changes to pkg/themes/default/templates/ don’t take effect
Rebuilding with go build doesn’t help

Solution:

go clean -cache
go install -a ./cmd/markata-go

The -a flag forces Go to rebuild all packages, ignoring the cache.

2. Markata Build Cache #

Problem: The .markata/ directory caches rendered HTML to speed up incremental builds.

Unchanged pages, including published frontmatter-only pages, restore their cached full-page HTML before the write stage. If you recreate the output directory while keeping .markata/, a normal or --fast build can materialize those pages again without clearing the build cache.

The cache also hashes the embedded default theme templates. A new builder image that changes those templates invalidates cached pages on its next build.

Symptoms:

Removing templates but still seeing cached output
Template changes not reflected in output

Solution:

rm -rf .markata
markata-go build --clean

Current releases should still detect moved or deleted content files during markata-go build --fast. If a moved-file error only goes away after clearing .markata/, you are likely hitting an older build-cache bug rather than expected behavior.

3. Config File Differences #

Problem: markata-go.toml points to wrong templates or has different settings.

Example Issue: Config pointed to old partials/card.html instead of new partials/cards/card-router.html.

Solution:

Check git status: git status
Compare configs: diff markata-go.toml <(git show HEAD:markata-go.toml)
Use diagnostic script: ./scripts/diagnose-build.sh

4. Different Git Commits #

Problem: Machines are on different branches or commits.

Symptoms:

Binary checksums differ
Template checksums differ

Solution:

git status
git log -1
git pull origin main  # or your branch

Diagnostic Tools #

Full Diagnostic #

Run this on both machines and compare output:

./scripts/diagnose-build.sh > ~/diagnostic.txt
cat ~/diagnostic.txt

Key things to compare:

Git commit hash
Binary SHA256 checksum
Template checksums (embedded vs project overrides)
Config file checksum

Clean Rebuild #

Use the automated clean rebuild script:

./scripts/clean-rebuild.sh

This script:

Checks git status
Cleans Go cache
Removes old binaries
Removes markata caches
Shows template checksums
Rebuilds and installs binary
Verifies installation

Expected Checksums (as of commit bfa19d0) #

Binary:

SHA256: 72393651937484c022ced092a80f5171353d8bc49320453a58a187ed1b168bcb

Key Templates (embedded in pkg/themes/default/templates/):

article-card.html: b9a26a3dbbec42e00aaea791772de29c4c1060cb1cd6047b4a8bf9e30e158d23
feed.html:         b4a5cab1c989446d62240e9e98126dc2dfc62accadc86775a2757c69788ad63a
card-router.html:  12c02e186b2ca95f9c65187f91661a2da994984895bcaf4d2cfea89658835627

Config:

markata-go.toml: a01e140d4788d732dddc1eb90f57b183781ebcbcbda78c90389eadf3e0691c9d

Card System #

Why No Card Types Appear #

The card router (partials/cards/card-router.html) selects card templates based on the post’s template field:

---
title: My Note
template: note  # This determines the card type!
---

Card types:

article, blog-post, post, essay, tutorial → article-card.html
note, ping, thought, status, tweet → note-card.html
photo, shot, shots, image, gallery → photo-card.html
video, clip, cast, stream → video-card.html
link, bookmark, stars → link-card.html
quote, quotation → quote-card.html
guide, series, step, chapter → guide-card.html
gratitude, inline, micro, til → inline-card.html
(no template field) → default-card.html

To get different card types, add template: to your post frontmatter:

---
title: "Quick Thought"
template: note
date: 2026-01-30
---

Workflow for Updates #

When you update templates:

# 1. Edit templates in pkg/themes/default/templates/
vim pkg/themes/default/templates/feed.html

# 2. Force rebuild to pick up embedded file changes
go clean -cache
go install -a ./cmd/markata-go

# 3. Clean build
rm -rf .markata public
markata-go build --clean

pkg/themes/embed.go - Embeds default templates into binary
pkg/templates/engine.go - Template loading order
markata-go.toml - Config including feed card template
templates/partials/cards/card-router.html - Card type router

Card Types

2026-01-29T00:00:00Z

Cards are how posts appear in feed listings. Different types of content benefit from different visual treatments - a photo post should emphasize the image, while a blog post should show the title and excerpt.

How Cards Are Selected #

Cards are selected based on the template frontmatter field:

---
title: "My Photo"
template: photo
---

Note: templateKey is supported as an alias for backwards compatibility with Python markata.

The template field determines:

Which card template renders the post in feeds
Which page template renders the full post (if defined)

Field Name Comparison #

markata-go uses template as the primary field, following Zola and Pelican conventions:

SSG	Field Name
Hugo, Jekyll, Eleventy, Astro	`layout`
Zola, Pelican, markata-go	`template`

Both template and templateKey work in markata-go frontmatter.

Card Types #

Card Type	template Values	Best For
`article`	`blog-post`, `article`, `post`, `essay`, `tutorial`	Long-form content with title, excerpt, tags
`note`	`note`, `ping`, `thought`, `status`, `tweet`	Short thoughts, micro-posts
`photo`	`photo`, `shot`, `shots`, `image`, `gallery`	Image-focused posts
`video`	`video`, `clip`, `cast`, `stream`	Video content with thumbnail
`link`	`link`, `bookmark`, `stars`	External links, bookmarks
`quote`	`quote`, `quotation`	Quoted text with attribution
`guide`	`guide`, `series`, `step`, `chapter`	Multi-part tutorials
`inline`	`gratitude`, `inline`, `micro`, `til`	Full content shown in feed
`contact`	`contact`, `character`, `person`	Person/character profile cards
`default`	(any other value)	Fallback for unmapped types

Linked posts and source previews #

A link, bookmark, stars, or til post with a link or url frontmatter destination preserves its local permalink and shows a visible Source link on the post page. Feed cards also link to the external domain.

---
title: "Worth watching"
template: link
link: "https://www.youtube.com/watch?v=R_uf5OfMGio"
published: true
---

My thoughts on the video.

The destination is automatically embedded before your commentary through the normal external embed system. YouTube uses the site’s Lite YouTube renderer; other URLs use cached oEmbed/Open Graph previews and fall back to a clickable source card when metadata is unavailable. No new Markdown is required. Explicit ![embed](url) or  ![[url]] in the body is not duplicated. Leave the link/url field unset if the post is not sharing an external destination.

Card Anatomy #

Each card type has different visual elements:

Article Card #

Large title (linked)
Content excerpt (first 3 paragraphs or 1500 characters)
Date, reading time
Tags

Note Card #

Compact layout with left accent border
Title (optional)
Short text content
Date

Photo Card #

Large image (16:9 aspect ratio)
Caption below
Date

Inline Card #

Full article_html content rendered in the feed
No “read more” - everything is visible
Useful for gratitude journals, micro-posts

Link Card #

Domain indicator
Title and description
External link styling

Contact Card #

Avatar (from avatar, image, or icon frontmatter fields)
Name (post title)
Handle (@handle)
Short bio (description)
External site link (from url frontmatter field, if set)
Tags

Default Card Images #

Posts without a mapped template use the default card. If the frontmatter contains image, cover, cover_image, or og_image, the card displays that media in a cinematic 12:5 frame. The source uses width-only sizing so the CDN does not distort the image; CSS crops it with object-fit: cover so portrait images do not make daily note cards too tall.

Examples #

Blog Post (article card) #

---
title: "Understanding Go Interfaces"
template: blog-post
tags:
  - go
  - programming
---

Your article content here. The first three paragraphs (or up to 1500 characters) will automatically be shown as the excerpt in feed listings.

Quick Thought (note card) #

---
title: "Ping 42"
template: ping
---

Just discovered that vim has a built-in terminal. Mind blown.

Photo (photo card) #

---
title: "Sunset at the Beach"
template: shots
image: /images/sunset.jpg
---

Gratitude Entry (inline card) #

---
template: gratitude
---

Today I'm grateful for good coffee and working CI pipelines.

Configuring Excerpts #

Article cards automatically show an excerpt from your content - the first 3 paragraphs or 1500 characters, whichever is shorter.

Default Behavior #

By default, article cards extract:

Up to 3 paragraphs from your rendered HTML content
OR up to 1500 characters (whichever comes first)
With intelligent truncation at word boundaries
An ellipsis (...) is added when content is truncated

How It Works #

The excerpt filter extracts <p> tags from your rendered article_html
It collects paragraphs until reaching 3 paragraphs OR 1500 characters
It strips inner HTML tags but preserves text
It adds ellipsis (...) if content was truncated
Output is safe HTML ready to render

Tips #

Short posts: If your post is shorter than the limit, the entire post shows (no ellipsis)
No paragraphs: If content has no <p> tags, the filter falls back to plain text truncation
Removal of description: The old description frontmatter field is no longer used for article cards - excerpts are auto-generated from content

Customizing Cards #

To override a built-in card, create a file in your site’s templates/partials/cards/ directory:

templates/
  partials/
    cards/
      article-card.html   # Overrides built-in article card
      my-custom-card.html # New card type

To add a new card type, create a custom card-router.html:

{% elif post.template == "my-type" %}
{% include "partials/cards/my-custom-card.html" %}

Card CSS #

Card styles are in themes/default/static/css/cards.css. Each card has a class:

.card-article
.card-note
.card-photo
.card-video
.card-link
.card-quote
.card-guide
.card-inline
.card-contact
.card-default

How It Works #

Feed template (feed.html) loops through posts
For each post, includes partials/cards/card-router.html
Card router checks post.template and includes the matching card template
Card template renders the post with appropriate HTML structure

<!-- feed.html -->
{% for post in page.posts %}
{% include "partials/cards/card-router.html" %}
{% endfor %}

<!-- card-router.html -->
{% if post.template == "blog-post" %}
{% include "partials/cards/article-card.html" %}
{% elif post.template == "ping" %}
{% include "partials/cards/note-card.html" %}
...
{% endif %}

Template Access in Custom Templates #

In your templates, you can access the template value via either name:

{# Both work - template is preferred #}
{{ post.template }}
{{ post.templateKey }}

Standard Web Txt Files

2026-01-26T00:00:00Z

markata-go supports generating standard web txt files at their expected canonical URLs. This enables creating files like robots.txt, llms.txt, and humans.txt that web crawlers, AI models, and humans expect to find at the root of your site.

Quick Start #

Text format is enabled by default - no configuration needed
Create a markdown file for your txt content:

<!-- robots.md -->
---
title: "Robots"
slug: robots
published: true
---

User-agent: *
Allow: /
Disallow: /private/

Build your site - markata-go generates:
- /robots.txt - The canonical robots.txt file
- /robots/index.txt - Redirect for backwards compatibility
- /robots/index.txt/index.html - HTML redirect for static hosts

Common Txt Files #

robots.txt #

The robot exclusion standard for web crawlers:

---
title: "Robots"
slug: robots
published: true
---

User-agent: *
Allow: /

User-agent: GPTBot
Disallow: /

Sitemap: https://example.com/sitemap.xml

llms.txt #

By default, a full-site build automatically creates /llms.txt using the site title and description, links to selected published documentation and recent posts, and a link to the sitemap when available. The index is capped at 30 pages (configurable) to keep it concise. Private, draft, skipped, unpublished, and noindex posts are not included. The generated links prefer the post’s .md version when that output format is enabled.

This follows the llms.txt v2 proposal: a Markdown H1, optional blockquote summary, and H2 sections with Markdown links. It is a discovery aid, not an instruction granting AI crawlers permission to train on content. Access rules belong in robots.txt and other applicable policies.

Example generated output:

# Example Site

> Notes on software, homelabs, and photography.

## Site

- [Home](https://example.com/): Site homepage

## Recent Content

- [A recent post](https://example.com/recent-post.md): A brief introduction.

## Optional

- [Sitemap](https://example.com/sitemap.xml): Complete index of publicly accessible pages

To configure the generated index:

[markata-go.llms_txt]
enabled = true       # default; set false to disable automatic generation
max_pages = 30       # default; accepted range 1-100

A published Markdown post with slug: llms (and text output enabled), a static/llms.txt file, or an existing manually managed output/llms.txt overrides the automatic content. This preserves the ability to write a curated index yourself. If you disable auto-generation, markata-go removes only its own previously generated file when no authored source exists. Private posts with slug: llms do not override the public index. Absolute links use the configured site URL only when it has no credentials, query, or fragment; otherwise generated links are relative.

humans.txt #

Human-readable site credits (humanstxt.org):

---
title: "Humans"
slug: humans
published: true
---

/* TEAM */
Developer: Jane Doe
Contact: jane@example.com
Twitter: @janedoe
Location: San Francisco, CA

/* SITE */
Last update: 2026/01/26
Standards: HTML5, CSS3
Software: markata-go

security.txt #

Security contact information (securitytxt.org):

---
title: "Security"
slug: .well-known/security
published: true
---

Contact: security@example.com
Expires: 2027-01-01T00:00:00.000Z
Preferred-Languages: en
Canonical: https://example.com/.well-known/security.txt

Auto-Generated .well-known Entries #

markata-go can generate additional .well-known endpoints directly from your site metadata. These do not require markdown source files.

Default Auto-Generated Entries #

/.well-known/host-meta
/.well-known/host-meta.json
/.well-known/webfinger
/.well-known/nodeinfo and /nodeinfo/2.0
/.well-known/time

Configuration #

[markata-go.well_known]
enabled = true
auto_generate = ["host-meta", "host-meta.json", "webfinger", "nodeinfo", "time"]

# Optional entries requiring config
ssh_fingerprint = "SHA256:abcdef..."
keybase_username = "username"

Notes:

If you set auto_generate = [], only optional entries with explicit config are generated.
Templates live under templates/well-known/ and can be overridden.

How It Works #

Reversed Redirects #

For .txt and .md formats, markata-go uses reversed redirects:

Canonical Location	Redirect From
`/robots.txt`	`/robots/index.txt`, `/robots/index.txt/index.html`
`/llms.txt`	`/llms/index.txt`, `/llms/index.txt/index.html`

This ensures:

Standard files work at their expected URLs
Backwards compatibility with directory-based URLs
Both URL styles are accessible

File Structure #

After building, your output directory contains:

output/
├── robots.txt                   ← Canonical content
├── robots/
│   └── index.txt/
│       └── index.html           ← HTML redirect to /robots.txt
├── llms.txt                     ← Canonical content
├── llms/
│   └── index.txt/
│       └── index.html           ← HTML redirect to /llms.txt
└── humans.txt                   ← Canonical content
    humans/
    └── index.txt/
        └── index.html           ← HTML redirect to /humans.txt

Configuration #

Text output is enabled by default. To customize:

[markata-go.post_formats]
html = true       # Standard HTML (default: true)
markdown = true   # Raw markdown at /slug.md (default: true)
text = true       # Plain text at /slug.txt (default: true)
og = true         # OpenGraph cards (default: true)

To disable text output:

[markata-go.post_formats]
text = false

Text File Format #

The plain text output includes:

Title (underlined with =)
Description (if present)
Date (if present)
Raw content (no markdown processing)

Example output for a post:

My Post Title
=============

A description of the post.

Date: January 26, 2026

The actual content of the post...

For standard txt files like robots.txt, keep the content minimal:

---
title: "Robots"
slug: robots
published: true
---

User-agent: *
Allow: /

This generates clean output without the title/description header:

Robots
======

User-agent: *
Allow: /

Testing #

Verify your txt files work:

# Build and serve locally
markata-go serve

# Test in another terminal
curl http://localhost:8000/robots.txt
curl http://localhost:8000/llms.txt
curl http://localhost:8000/humans.txt

# Test redirects
curl -L http://localhost:8000/robots/index.txt

WebMentions & Social Bridging

2026-01-24T00:00:00Z

markata-go supports the IndieWeb WebMention protocol for connecting your static site to the decentralized social web. This includes:

Outgoing WebMentions: Automatically notify sites you link to
Social Media Bridging: Receive likes, reposts, and replies from Twitter, Bluesky, Mastodon, and more

Quick Start #

Enable WebMentions in your markata-go.toml:

[markata-go.webmentions]
enabled = true

# For outgoing mentions
outgoing = true

# For social media bridging
[markata-go.webmentions.bridges]
enabled = true
bluesky = true
twitter = true
mastodon = true

Outgoing WebMentions #

When you link to external sites in your posts, markata-go can automatically send WebMentions to those sites (if they support the protocol).

How It Works #

During build, markata-go scans your posts for external links
For each link, it discovers the target site’s WebMention endpoint
It sends a notification: “Hey, this URL linked to you!”
The target site can then display your link/comment

Configuration #

[markata-go.webmentions]
enabled = true
outgoing = true

# HTTP request timeout
timeout = "30s"

# Max concurrent requests
concurrent_requests = 5

# Cache directory to avoid re-sending
cache_dir = ".cache/webmentions"

# Custom User-Agent string
user_agent = "MySite/1.0 (WebMention; +https://mysite.com)"

Caching #

Sent WebMentions are cached to avoid re-sending on every build. The cache is stored in the configured cache_dir as JSON.

Social media bridging allows you to receive interactions from Twitter, Bluesky, Mastodon, and other platforms as WebMentions. This is powered by services like Bridgy Fed.

Supported Platforms #

Platform	Interactions	Detection
Bluesky	Likes, reposts, replies	bsky.app URLs, Bridgy
Twitter/X	Likes, retweets, replies	twitter.com/x.com URLs
Mastodon	Favorites, boosts, replies	Fediverse patterns
GitHub	Stars, comments, issues	github.com URLs
Flickr	Favorites, comments	flickr.com URLs

Setting Up Bridging #

Sign up for webmention.io to receive incoming mentions
Connect Bridgy Fed to your social accounts at fed.brid.gy
Configure markata-go:

[markata-go.webmentions]
enabled = true
webmention_io_token = "your_token_here"

[markata-go.webmentions.bridges]
enabled = true
bridgy_fediverse = true

# Enable specific platforms
bluesky = true
twitter = true
mastodon = true
github = true
flickr = false

Platform Detection #

markata-go automatically detects the source platform of incoming WebMentions by analyzing:

URL patterns: brid.gy/publish/bluesky, bsky.app, etc.
Domain matching: Known Mastodon instances, GitHub, etc.
Content patterns: Platform-specific indicators in mention content

Each detected mention is enriched with:

Platform name: “bluesky”, “twitter”, “mastodon”, etc.
Handle: Platform-specific username (e.g., @alice.bsky.social)
Original URL: Link back to the original interaction

Filtering Bridged Mentions #

You can filter incoming mentions by platform, interaction type, or content:

[markata-go.webmentions.bridges.filters]
# Only accept from these platforms
platforms = ["bluesky", "mastodon"]

# Only accept these interaction types
# Options: "like", "repost", "reply", "bookmark", "mention"
interaction_types = ["like", "repost", "reply"]

# Minimum content length for replies
min_content_length = 10

# Block specific domains
blocked_domains = ["spam-site.com", "bad-actor.net"]

Template Integration #

Display WebMentions in your templates:

{% if post.webmentions %}
<section class="webmentions">
  <h3>Reactions</h3>

  {% for mention in post.webmentions %}
  <article class="webmention webmention--{{ mention.platform }}">
    <!-- Platform badge -->
    {% if mention.platform != "web" %}
    <span class="platform-badge">
      {% if mention.platform == "bluesky" %}Bluesky
      {% elif mention.platform == "twitter" %}Twitter
      {% elif mention.platform == "mastodon" %}Mastodon
      {% elif mention.platform == "github" %}GitHub
      {% endif %}
    </span>
    {% endif %}

    <!-- Author info -->
    <div class="author">
      {% if mention.author.photo %}
      <img src="{{ mention.author.photo }}" alt="{{ mention.author.name }}">
      {% endif %}
      <a href="{{ mention.author.url }}">
        {{ mention.handle | default(mention.author.name) }}
      </a>
    </div>

    <!-- Interaction type -->
    {% if mention.wm_property == "like-of" %}
      <p>Liked this post</p>
    {% elif mention.wm_property == "repost-of" %}
      <p>Reposted this post</p>
    {% elif mention.wm_property == "in-reply-to" %}
      <blockquote>{{ mention.content.text }}</blockquote>
    {% endif %}

    <!-- Link to original -->
    {% if mention.original_url %}
    <a href="{{ mention.original_url }}">View on {{ mention.platform }}</a>
    {% endif %}
  </article>
  {% endfor %}
</section>
{% endif %}

Platform-Specific Styling #

/* Platform colors */
.platform-badge--bluesky { background: #0085ff; }
.platform-badge--twitter { background: #1da1f2; }
.platform-badge--mastodon { background: #6364ff; }
.platform-badge--github { background: #333; }

/* Platform borders */
.webmention--bluesky { border-left: 3px solid #0085ff; }
.webmention--twitter { border-left: 3px solid #1da1f2; }
.webmention--mastodon { border-left: 3px solid #6364ff; }
.webmention--github { border-left: 3px solid #333; }

Fetching WebMentions #

WebMentions are fetched from webmention.io and cached locally. The build process reads from the cache, so you need to periodically fetch fresh mentions.

Fetching with CLI #

# Fetch all webmentions for your site
markata-go webmentions fetch

# The mentions are saved to .cache/webmentions/received_mentions.json

Environment Variable #

You can set your webmention.io token via environment variable instead of config:

export WEBMENTION_IO_TOKEN="your_token_here"
markata-go webmentions fetch

Automated Fetching #

Set up a cron job or CI workflow to fetch mentions regularly:

# .github/workflows/fetch-webmentions.yml
name: Fetch WebMentions
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:

jobs:
  fetch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Fetch webmentions
        run: markata-go webmentions fetch
        env:
          WEBMENTION_IO_TOKEN: ${{ secrets.WEBMENTION_IO_TOKEN }}
      - name: Commit cache
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add .cache/webmentions/
          git diff --staged --quiet || git commit -m "chore: update webmention cache"
          git push

Displaying Counts on Post Cards #

The default theme includes a webmention counts partial that shows like/repost/reply counts on post cards.

Including the Partial #

Add to your card templates (e.g., article-card.html):

<article class="article-card">
  <a href="{{ post.Href }}">
    <h3>{{ post.Title }}</h3>
    <p>{{ post.Description }}</p>
  </a>
  <footer>
    <time>{{ post.Date.Format "Jan 2, 2006" }}</time>
    {% include "partials/webmention-counts.html" %}
  </footer>
</article>

The Counts Partial #

The partials/webmention-counts.html partial renders compact counts:

{% if post.Extra.webmentions %}
{% set likes = post.Extra.webmentions|selectattr("WMProperty", "equalto", "like-of")|list|length %}
{% set reposts = post.Extra.webmentions|selectattr("WMProperty", "equalto", "repost-of")|list|length %}
{% set replies = post.Extra.webmentions|selectattr("WMProperty", "equalto", "in-reply-to")|list|length %}

{% if likes > 0 or reposts > 0 or replies > 0 %}
<div class="webmention-counts">
  {% if likes > 0 %}<span class="wm-count wm-likes" title="Likes">{{ likes }}</span>{% endif %}
  {% if reposts > 0 %}<span class="wm-count wm-reposts" title="Reposts">{{ reposts }}</span>{% endif %}
  {% if replies > 0 %}<span class="wm-count wm-replies" title="Replies">{{ replies }}</span>{% endif %}
</div>
{% endif %}
{% endif %}

Styling Counts #

The default theme uses semantic color variables:

.webmention-counts {
  display: flex;
  gap: 0.75rem;
  font-size: 0.875rem;
}

.wm-count {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
}

.wm-count::before {
  font-size: 1rem;
}

.wm-likes::before { content: ""; color: var(--color-error); }
.wm-reposts::before { content: ""; color: var(--color-success); }
.wm-replies::before { content: ""; color: var(--color-primary); }

Engagement Leaderboard #

The webmentions_leaderboard plugin calculates top posts by engagement and makes the data available for analytics pages.

Enabling the Leaderboard #

The leaderboard plugin runs automatically when webmentions are present. No additional configuration needed.

Accessing Leaderboard Data #

In any Jinja-enabled page, access the leaderboard via config.Extra.webmention_leaderboard:

---
title: "Site Analytics"
jinja: true
---

# Content Analytics

{% if config.Extra.webmention_leaderboard %}

## Most Liked Posts

| Likes | Post |
|------:|------|
{% for entry in config.Extra.webmention_leaderboard.TopLiked %}| {{ entry.Likes }} | [{{ entry.Title }}]({{ entry.Href }}) |
{% endfor %}

## Most Discussed Posts

| Replies | Post |
|--------:|------|
{% for entry in config.Extra.webmention_leaderboard.TopReplied %}| {{ entry.Replies }} | [{{ entry.Title }}]({{ entry.Href }}) |
{% endfor %}

## Most Shared Posts

| Reposts | Post |
|--------:|------|
{% for entry in config.Extra.webmention_leaderboard.TopReposted %}| {{ entry.Reposts }} | [{{ entry.Title }}]({{ entry.Href }}) |
{% endfor %}

## Top Engaged Posts (Total)

| Total | Likes | Reposts | Replies | Post |
|------:|------:|--------:|--------:|------|
{% for entry in config.Extra.webmention_leaderboard.TopTotal %}| {{ entry.Total }} | {{ entry.Likes }} | {{ entry.Reposts }} | {{ entry.Replies }} | [{{ entry.Title }}]({{ entry.Href }}) |
{% endfor %}

---

## Site Totals

- **Total Likes:** {{ config.Extra.webmention_leaderboard.TotalLikes }}
- **Total Reposts:** {{ config.Extra.webmention_leaderboard.TotalReposts }}
- **Total Replies:** {{ config.Extra.webmention_leaderboard.TotalReplies }}
- **Total Mentions:** {{ config.Extra.webmention_leaderboard.TotalMentions }}

{% else %}
*No webmention data available.*
{% endif %}

Leaderboard Data Structure #

Field	Type	Description
`TopLiked`	`[]LeaderboardEntry`	Top 20 posts by likes
`TopReposted`	`[]LeaderboardEntry`	Top 20 posts by reposts
`TopReplied`	`[]LeaderboardEntry`	Top 20 posts by replies
`TopTotal`	`[]LeaderboardEntry`	Top 20 posts by total engagement
`TotalLikes`	`int`	Site-wide total likes
`TotalReposts`	`int`	Site-wide total reposts
`TotalReplies`	`int`	Site-wide total replies
`TotalMentions`	`int`	Site-wide total mentions

Each LeaderboardEntry contains:

Field	Type	Description
`Href`	`string`	Post URL
`Title`	`string`	Post title
`Likes`	`int`	Number of likes
`Reposts`	`int`	Number of reposts
`Replies`	`int`	Number of replies
`Bookmarks`	`int`	Number of bookmarks
`Mentions`	`int`	Number of generic mentions
`Total`	`int`	Total engagement

Full Configuration Reference #

[markata-go.webmentions]
# Enable the webmentions plugin
enabled = true

# Send outgoing webmentions when linking to external sites
outgoing = true

# HTTP request timeout for sending/receiving
timeout = "30s"

# Directory to cache sent webmentions (avoids re-sending)
cache_dir = ".cache/webmentions"

# Maximum concurrent HTTP requests
concurrent_requests = 5

# User-Agent string for HTTP requests
user_agent = "markata-go/1.0 (WebMention; +https://github.com/WaylonWalker/markata-go)"

# API token for webmention.io (for receiving mentions)
webmention_io_token = ""

[markata-go.webmentions.bridges]
# Enable social media bridging detection
enabled = false

# Use Bridgy Fediverse for bridging
bridgy_fediverse = true

# Platform toggles
bluesky = true
twitter = true
mastodon = true
github = true
flickr = false

[markata-go.webmentions.bridges.filters]
# Limit to specific platforms (empty = all enabled)
platforms = []

# Limit to specific interaction types (empty = all)
# Options: "like", "repost", "reply", "bookmark", "mention"
interaction_types = []

# Minimum content length for replies
min_content_length = 0

# Block mentions from these domains
blocked_domains = []

Troubleshooting #

WebMentions not being sent #

Ensure enabled = true and outgoing = true
Check that target sites have WebMention endpoints
Review the cache directory for sent status
Check HTTP timeout settings

Bridged mentions not appearing #

Verify your webmention.io token is correct
Check that Bridgy is connected to your social accounts
Ensure the platform is enabled in bridges config
Check filters aren’t blocking the mentions

Platform not detected correctly #

The platform detection uses URL patterns. If a mention isn’t being detected:

Check the source URL in the raw WebMention data
Ensure the platform is enabled in config
File an issue if detection should be improved

Resources #

WebMention Spec
Bridgy Fed - Social media bridging
webmention.io - Hosted WebMention receiver
IndieWeb Wiki

Quick Reference

2026-01-24T00:00:00Z

A quick reference for common markata-go commands, configuration snippets, and troubleshooting tips.

Prerequisites #

Before using this guide, you should have:

markata-go installed ([Installation Guide](/docs/getting-started/#installation))
A basic understanding of TOML configuration format

CLI Commands #

Build and Serve #

# Build site
markata-go build

# Build with clean output directory
markata-go build --clean

# Build to custom output directory
markata-go build -o dist

# Start development server with live reload
markata-go serve

# Serve on custom port
markata-go serve -p 3000

# Serve with verbose output
markata-go serve -v

Content Creation #

# Create a new post
markata-go new "My Post Title"

# Create with specific template
markata-go new "Tutorial" -t tutorial

# Create in specific directory
markata-go new "About" --dir pages

# Create as published (not draft)
markata-go new "Announcement" --draft=false

# List available templates
markata-go new --list

Configuration #

# Initialize config file
markata-go config init

# Show resolved configuration
markata-go config show

# Show as JSON
markata-go config show --json

# Get specific value
markata-go config get output_dir
markata-go config get glob.patterns

# Validate configuration
markata-go config validate

Themes and Palettes #

# List available palettes
markata-go palette list

# Show palette details
markata-go palette info catppuccin-mocha

# Check accessibility
markata-go palette check catppuccin-mocha

# Export palette as CSS
markata-go palette export catppuccin-mocha --format css

# Clone a palette for customization
markata-go palette clone catppuccin-mocha --name "my-theme"

Rich Markdown icon shortcuts #

Use the existing Lucide shortcode in any Markdown post:

:lucide-rocket: Deployment

::: md-feature

:::: md-feature-icon
:lucide-rocket:

::::

:::: md-feature-body
### Verify production
Confirm the deployed image, with visible text for accessibility.

::::

:::

Combine md-icon with md-card for centered icon cards. See Icon Shortcodes and Markdown Containers. Agents should read the bundled skill’s topics/rich-markdown.md before inventing custom icon code.

Configuration Snippets #

Minimal Site Config #

[markata-go]
title = "My Site"
url = "https://example.com"
output_dir = "public"

[markata-go.glob]
patterns = ["posts/**/*.md"]

Blog with RSS #

[markata-go]
title = "My Blog"
url = "https://myblog.com"
output_dir = "public"

[markata-go.glob]
patterns = ["posts/**/*.md", "pages/*.md"]

[[markata-go.feeds]]
slug = "blog"
title = "Blog"
filter = "published == True"
sort = "date"
reverse = true

[markata-go.feeds.formats]
html = true
rss = true
atom = true

Documentation Site #

[markata-go]
title = "Project Docs"
url = "https://docs.example.com"
output_dir = "site"

[markata-go.glob]
patterns = ["docs/**/*.md"]

[markata-go.markdown]
extensions = ["tables", "tasklist"]

[markata-go.components.doc_sidebar]
enabled = true
position = "right"
min_depth = 2
max_depth = 4

[search]
enabled = true
position = "navbar"

Custom Theme #

[markata-go.theme]
palette = "catppuccin-mocha"
custom_css = "custom.css"

[markata-go.theme.variables]
"--color-primary" = "#8b5cf6"
"--content-width" = "800px"

[markata-go.components.nav]
enabled = true
position = "header"

[[markata-go.components.nav.items]]
label = "Home"
url = "/"

[[markata-go.components.nav.items]]
label = "Blog"
url = "/blog/"

[[markata-go.components.nav.items]]
label = "GitHub"
url = "https://github.com/user"
external = true

Frontmatter Snippets #

Basic Post #

---
title: "My Post"
date: 2026-01-24
published: true
tags:
  - topic
---

Full Post with Custom Fields #

---
title: "Complete Guide to X"
slug: "guide-to-x"
date: 2026-01-24
published: true
tags:
  - tutorial
  - guide
description: "A comprehensive guide covering everything about X."
template: "tutorial.html"

# Custom fields (available via post.Extra)
author: "Jane Doe"
reading_time: "10 min"
featured: true
series: "X Fundamentals"
series_order: 1
---

Draft Post #

---
title: "Work in Progress"
date: 2026-01-24
published: false
draft: true
---

Landing Page #

---
title: "Welcome"
slug: ""
published: true
template: "landing.html"
---

Filter Expressions #

Common filter expressions for feed configuration:

# Published posts only
filter = "published == True"

# Exclude drafts
filter = "published == True and draft == False"

# Posts with specific tag
filter = "'tutorial' in tags"

# Multiple tags (OR)
filter = "'python' in tags or 'go' in tags"

# Date range
filter = "date >= '2024-01-01' and date < '2025-01-01'"

# No future posts
filter = "published == True and date <= today"

# Featured posts
filter = "published == True and featured == True"

# By author (custom field)
filter = "author == 'Jane Doe'"

# Slug prefix (for sections)
filter = "slug.startswith('tutorials/')"

Template Snippets #

Date Formatting #

{{ post.Date|date_format:"January 2, 2006" }}
{{ post.Date|date_format:"2006-01-02" }}
{{ post.Date|rss_date }}
{{ post.Date|atom_date }}

Conditional Content #

{% if post.Tags %}
<ul class="tags">
  {% for tag in post.Tags %}
  <li><a href="/tags/{{ tag|slugify }}/">{{ tag }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Custom Field Access #

{% if post.Extra.featured %}
<span class="badge">Featured</span>
{% endif %}

{% if post.Extra.author %}
<p>By {{ post.Extra.author }}</p>
{% endif %}

Pagination #

{% if page.HasPrev or page.HasNext %}
<nav class="pagination">
  {% if page.HasPrev %}
  <a href="{{ page.PrevURL }}">Previous</a>
  {% endif %}
  <span>Page {{ page.Number }}</span>
  {% if page.HasNext %}
  <a href="{{ page.NextURL }}">Next</a>
  {% endif %}
</nav>
{% endif %}

Environment Variables #

Override any config with MARKATA_GO_ prefix:

# Core settings
export MARKATA_GO_OUTPUT_DIR=dist
export MARKATA_GO_URL=https://example.com
export MARKATA_GO_TITLE="My Site"

# Build with overrides
MARKATA_GO_URL=https://staging.example.com markata-go build

Quick Troubleshooting #

Site Not Updating #

# Clean build
markata-go build --clean

# Clear browser cache or use incognito mode

Posts Not Appearing #

Check frontmatter: published: true must be set
Check filter: Ensure feed filter matches your posts
Check date: Future dates won’t appear with date <= today filter

# Validate config
markata-go config validate

# Check resolved config
markata-go config show

RSS Feed Empty #

Verify RSS is enabled in feed formats:
```
[markata-go.feeds.formats]
rss = true
```
Check that posts match the feed filter
Ensure url is set in config (required for absolute URLs)

Template Not Found #

Check template path in frontmatter matches file name
Verify file exists in templates/ directory
Include .html extension: template: "custom.html"

Styles Not Loading #

Check static/ directory contains CSS files
Verify assets_dir setting if using custom location
Check browser console for 404 errors

Build Fails #

# Verbose output for debugging
markata-go build -v

# Validate configuration first
markata-go config validate

Common File Locations #

Purpose	Default Location
Configuration	`./markata-go.toml`
Content	`./posts/*/.md`
Templates	`./templates/`
Static assets	`./static/`
Build output	`./public/`
Custom CSS	`./static/custom.css`

Next Steps #

Getting Started - Full installation tutorial
Configuration Guide - Complete config reference
Troubleshooting - Detailed problem solutions
Guides Hub - Learning paths and all guides

Troubleshooting Quality Checks

2026-01-24T00:00:00Z

This guide covers common issues you may encounter when setting up and running content quality checks for your markata-go site, along with their solutions.

Table of Contents #

Pre-commit Hook Issues #

Hooks Not Running #

Symptom: Pre-commit hooks don’t execute when you commit.

Solutions:

Reinstall hooks:

pre-commit uninstall
pre-commit install

Verify git hooks directory:

ls -la .git/hooks/
# Should see pre-commit -> /path/to/pre-commit-hook

Check pre-commit installation:

pre-commit --version
# If not found, reinstall: pip install pre-commit

Verify configuration file exists:
```
ls -la .pre-commit-config.yaml
```

Hook Fails with “Command Not Found” #

Symptom: Hook fails because it can’t find a command like markdownlint or yamllint.

Solutions:

For system hooks, install the tool globally:

# markdownlint
npm install -g markdownlint-cli

# yamllint
pip install yamllint

Use repository-based hooks instead of local hooks:

# Instead of local hook:
- repo: https://github.com/igorshubovych/markdownlint-cli
  rev: v0.42.0
  hooks:
    - id: markdownlint

Check PATH in your shell:
```
echo $PATH
which markdownlint
```

Hooks Running Too Slowly #

Symptom: Commits take a long time because hooks are slow.

Solutions:

Limit files processed:

hooks:
  - id: markdownlint
    files: ^docs/  # Only check docs directory

Skip slow hooks for WIP commits:

SKIP=check-links git commit -m "WIP: quick save"

Move slow checks to CI only:

# In .pre-commit-config.yaml
hooks:
  - id: check-links
    stages: [push]  # Only run on push, not commit

Clear pre-commit cache:
```
pre-commit clean
pre-commit gc
```

Skipping Hooks Temporarily #

When to skip: Emergency fixes, work-in-progress commits, or when hooks have false positives.

# Skip all hooks (use sparingly!)
git commit --no-verify -m "Emergency fix"

# Skip specific hooks
SKIP=markdownlint,check-links git commit -m "Quick fix"

# Skip hooks for a single file
git add -f file-with-issues.md

Warning: Skipping hooks bypasses quality checks. Use CI/CD as a safety net.

Markdown Linting Issues #

MD013: Line Length Errors #

Symptom: MD013/line-length: Line length [expected: 80, actual: 150]

Solutions:

Disable for prose (recommended for content sites):
```
{
  "MD013": false
}
```

Increase line length limit:

{
  "MD013": {
    "line_length": 120,
    "code_blocks": false,
    "tables": false
  }
}

Disable for specific file:

<!-- markdownlint-disable-file MD013 -->

# My Document

This file allows long lines...

MD033: Inline HTML Warnings #

Symptom: MD033/no-inline-html: Inline HTML [Element: details]

Solutions:

Allow specific HTML elements:

{
  "MD033": {
    "allowed_elements": [
      "details", "summary", "kbd", "br",
      "sup", "sub", "img", "video"
    ]
  }
}

Disable for a section:

<!-- markdownlint-disable MD033 -->
<details>
<summary>Click to expand</summary>

Content here...

</details>
<!-- markdownlint-enable MD033 -->

Disable entirely (not recommended):
```
{
  "MD033": false
}
```

MD041: First Line Should Be Heading #

Symptom: MD041/first-line-heading: First line in file should be a top-level heading

Why it happens: Files with YAML frontmatter trigger this because the first content line isn’t a heading.

Solution:

{
  "MD041": false
}

Or configure to recognize frontmatter:

{
  "MD025": {
    "front_matter_title": "^\\s*title\\s*[:=]"
  },
  "MD041": false
}

MD024: Duplicate Headings #

Symptom: MD024/no-duplicate-heading: Multiple headings with the same content

Solution: Allow duplicate headings for siblings only:

{
  "MD024": {
    "siblings_only": true
  }
}

This allows:

## Installation  <!-- OK: different parent -->

### Step 1

## Configuration

### Step 1  <!-- OK: different parent section -->

False Positives in Code Blocks #

Symptom: Linting errors appear for content inside code blocks.

Solutions:

Ensure code blocks are properly fenced:

```bash
# This is code, not a heading
echo "hello"

Check for missing language identifier:

{
  "MD040": true  // Enforces language specification
}

Verify backtick count matches:

```python
code here
```  <!-- Must have same number of backticks -->

YAML/Frontmatter Issues #

Invalid YAML Syntax #

Symptom: yaml: line 3: mapping values are not allowed here

Common causes and fixes:

Unquoted special characters:

# Wrong
title: My Post: A Journey

# Correct
title: "My Post: A Journey"

Improper indentation:

# Wrong (tabs)
tags:
	- documentation

# Correct (2 spaces)
tags:
  - documentation

Missing quotes around dates:

# Wrong (may be interpreted as number)
version: 1.0

# Correct
version: "1.0"

Frontmatter Not Detected #

Symptom: Frontmatter is treated as content, not metadata.

Causes:

No opening delimiter on first line:

<!-- Wrong: whitespace before --- -->
 ---
title: My Post
---

<!-- Correct: --- must be on line 1 -->
---
title: My Post
---

Wrong delimiter:

<!-- Wrong -->
----
title: My Post
----

<!-- Correct: exactly three dashes -->
---
title: My Post
---

BOM or hidden characters:

# Check for BOM
file your-file.md
# Should show: UTF-8 Unicode text
# NOT: UTF-8 Unicode (with BOM) text

# Remove BOM
sed -i '1s/^\xEF\xBB\xBF//' your-file.md

Required Field Missing #

Symptom: Build fails with “missing required field: title”

Solutions:

Add missing field:

---
title: "My Post Title"
date: 2026-01-24
published: true
---

Check field spelling:

# Wrong
titel: "My Post"

# Correct
title: "My Post"

Check for invisible characters:

# View hex dump of frontmatter
head -5 your-file.md | xxd

Date Format Issues #

Symptom: Invalid date format or dates not sorting correctly.

Correct formats:

# ISO 8601 (recommended)
date: 2026-01-24

# With time
date: 2026-01-24T10:30:00

# With timezone
date: 2026-01-24T10:30:00-05:00

Wrong formats:

# Wrong: needs quotes or different format
date: January 24, 2026

# Wrong: ambiguous
date: 01/24/2026

Link Checking Issues #

Rate Limiting #

Symptom: Link checks fail with 429 Too Many Requests.

Solutions:

Configure retry behavior:

{
  "retryOn429": true,
  "retryCount": 5,
  "fallbackRetryDelay": "30s"
}

Add delays between requests:

# .lychee.toml
max_concurrency = 5
delay = 1

Exclude problematic domains:

{
  "ignorePatterns": [
    { "pattern": "^https://twitter\\.com" },
    { "pattern": "^https://x\\.com" }
  ]
}

False Positives on Valid Links #

Symptom: Link checker reports broken links that work in browser.

Common causes:

Bot detection:

# .lychee.toml
user_agent = "Mozilla/5.0 (compatible; link-checker)"

Authentication required:

{
  "ignorePatterns": [
    { "pattern": "^https://private-site\\.com" }
  ]
}

JavaScript-rendered content:
- Link checkers can’t execute JavaScript
- Add to ignore list if the link is valid

Redirect chains:

{
  "aliveStatusCodes": [200, 206, 301, 302, 307, 308]
}

Internal Links Not Resolving #

Symptom: Relative links like /docs/guide/ reported as broken.

Solutions:

Configure base URL:

{
  "replacementPatterns": [
    {
      "pattern": "^/",
      "replacement": "https://example.com/"
    }
  ]
}

Run link checker on built output:

# Build first
markata-go build

# Check built HTML
lychee ./public/**/*.html

Use relative path resolution:

# .lychee.toml
base = "https://example.com"

Mailto and Tel Links #

Symptom: mailto: and tel: links reported as broken.

Solution: Exclude these patterns:

{
  "ignorePatterns": [
    { "pattern": "^mailto:" },
    { "pattern": "^tel:" }
  ]
}

Or in lychee:

# .lychee.toml
exclude = [
  "^mailto:",
  "^tel:",
]

CI/CD Pipeline Issues #

Pipeline Not Triggering #

Symptom: Push/MR doesn’t start the pipeline.

GitHub Actions solutions:

Check workflow file location:

.github/workflows/quality.yml  # Correct
.github/workflow/quality.yml   # Wrong (missing 's')

Verify trigger configuration:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

Check for YAML syntax errors:

# Validate workflow file
yamllint .github/workflows/quality.yml

GitLab CI solutions:

Check file name:

.gitlab-ci.yml  # Correct
gitlab-ci.yml   # Wrong (missing leading dot)

Validate configuration:

# In GitLab UI: CI/CD > Pipelines > CI Lint
# Or use API

Job Fails with Exit Code 1 #

Symptom: Job fails but output doesn’t show clear error.

Solutions:

Add verbose output:

script:
  - markdownlint '**/*.md' --verbose

Check previous command exit codes:

script:
  - set -e  # Exit on first error
  - markdownlint '**/*.md'
  - echo "Lint passed"

Use || true for non-blocking checks:

script:
  - markdownlint '**/*.md' || true  # Continue even if fails

Artifacts Not Available #

Symptom: Built files not available in later jobs.

GitHub Actions:

jobs:
  build:
    steps:
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: public/

  test:
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: site
          path: public/

GitLab CI:

build:
  artifacts:
    paths:
      - public/
    expire_in: 1 hour

test:
  needs:
    - job: build
      artifacts: true

Cache Not Working #

Symptom: Dependencies re-download every run.

GitHub Actions:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # Enable built-in caching

GitLab CI:

variables:
  npm_config_cache: $CI_PROJECT_DIR/.npm

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - .npm/
  policy: pull-push  # Important: must be pull-push

Performance Issues #

Pre-commit Runs Slowly #

Diagnosis:

# Time individual hooks
time pre-commit run markdownlint --all-files
time pre-commit run yamllint --all-files

Optimizations:

Limit scope:

hooks:
  - id: markdownlint
    files: ^docs/  # Only docs directory

Use faster alternatives:
- markdownlint-cli2 is faster than markdownlint-cli
- lychee is faster than markdown-link-check

Skip expensive checks on commit:

hooks:
  - id: check-links
    stages: [push]  # Only on push

CI/CD Takes Too Long #

Optimizations:

Run jobs in parallel:

# GitHub Actions
jobs:
  lint:
    runs-on: ubuntu-latest
  build:
    runs-on: ubuntu-latest
    needs: []  # No dependency = parallel

Use caching effectively:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('package-lock.json') }}

Only run on relevant changes:

on:
  push:
    paths:
      - '**/*.md'
      - '.markdownlint.json'

Use lightweight images:

# Instead of: image: node:20
image: node:20-alpine  # Much smaller

Migration from Other Tools #

From Jekyll #

Frontmatter differences:

# Jekyll
---
layout: post
title: My Post
categories: blog
---

# markata-go
---
title: "My Post"
date: 2026-01-24
published: true
tags:
  - blog
---

Conversion script:

#!/bin/bash
# Convert Jekyll frontmatter to markata-go format
for file in _posts/*.md; do
  # Add published: true if missing
  if ! grep -q "^published:" "$file"; then
    sed -i '/^---$/,/^---$/{/^title:/a published: true
    }' "$file"
  fi
done

From Hugo #

Frontmatter differences:

# Hugo
---
title: "My Post"
date: 2026-01-24T10:00:00-05:00
draft: true
---

# markata-go
---
title: "My Post"
date: 2026-01-24
published: false
---

Key changes:

draft: true becomes published: false
Date format simplified (time optional)
Remove Hugo-specific fields like weight, type

From Gatsby/MDX #

MDX components won’t work directly. Convert to standard Markdown:

// Gatsby MDX
<Callout type="info">
  Important information here
</Callout>

// markata-go Markdown
> **Info:** Important information here

Or use HTML:

<details>
<summary>Important information</summary>

Content here...

</details>

Getting Help #

If you can’t resolve an issue:

Check existing issues: Search GitHub Issues
Enable verbose output: Add --verbose or -v flags to commands
Isolate the problem: Create a minimal reproduction case

Gather information:

# System info
uname -a
go version
node --version
python --version

# Tool versions
pre-commit --version
markdownlint --version

Open an issue with:
- What you expected
- What actually happened
- Steps to reproduce
- Relevant configuration files
- Error messages (full output)

Pre-commit Hooks for Content Quality

2026-01-24T00:00:00Z

Pre-commit hooks automatically validate your content before each commit, catching issues early in the development cycle. This guide shows you how to set up comprehensive content quality checks for your markata-go site.

Table of Contents #

Installation #

Install pre-commit #

# macOS (Homebrew)
brew install pre-commit

# Python (pip) - works on all platforms
pip install pre-commit

# Python (pipx) - isolated installation
pipx install pre-commit

# Conda
conda install -c conda-forge pre-commit

Verify Installation #

pre-commit --version
# pre-commit 3.7.0

Initialize in Your Project #

# Create initial configuration
pre-commit sample-config > .pre-commit-config.yaml

# Install git hooks
pre-commit install

# Optional: Install for commit messages too
pre-commit install --hook-type commit-msg

Basic Configuration #

Create .pre-commit-config.yaml in your site’s root directory:

# .pre-commit-config.yaml
default_language_version:
  python: python3

repos:
  # Basic file checks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
        args: [--markdown-linebreak-ext=md]
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: [--maxkb=1024]
      - id: mixed-line-ending
        args: [--fix=lf]

Running Pre-commit #

# Run on staged files (automatic on commit)
pre-commit run

# Run on all files
pre-commit run --all-files

# Run specific hook
pre-commit run markdownlint --all-files

# Update hooks to latest versions
pre-commit autoupdate

YAML Frontmatter Validation #

markata-go uses YAML frontmatter for post metadata. Validating this frontmatter catches syntax errors before they break your build.

Using yamllint #

Add yamllint to your pre-commit config:

repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [--config-file, .yamllint.yml]
        files: \.(md|markdown)$

Create .yamllint.yml for Markdown frontmatter:

# .yamllint.yml
extends: relaxed

rules:
  # Frontmatter doesn't need document start markers
  document-start: disable
  
  # Allow long lines in frontmatter (descriptions, etc.)
  line-length: disable
  
  # Allow trailing spaces (some editors add them)
  trailing-spaces: disable
  
  # Require consistent indentation
  indentation:
    spaces: 2
    indent-sequences: true
  
  # Ensure proper quoting
  quoted-strings:
    quote-type: any
    required: only-when-needed
  
  # Check for duplicate keys
  key-duplicates: enable
  
  # Ensure proper boolean values
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']

Custom Frontmatter Validation Script #

For more specific frontmatter validation, create a custom script:

#!/bin/bash
# scripts/validate-frontmatter.sh
# Validates that required frontmatter fields exist

set -e

required_fields=("title" "date" "published")
errors=0

for file in "$@"; do
    # Skip non-markdown files
    [[ "$file" != *.md ]] && continue
    
    # Extract frontmatter (between first two ---)
    frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d')
    
    if [ -z "$frontmatter" ]; then
        echo "ERROR: $file - No frontmatter found"
        ((errors++))
        continue
    fi
    
    for field in "${required_fields[@]}"; do
        if ! echo "$frontmatter" | grep -q "^${field}:"; then
            echo "ERROR: $file - Missing required field: $field"
            ((errors++))
        fi
    done
    
    # Check that published is boolean
    published=$(echo "$frontmatter" | grep "^published:" | cut -d: -f2 | tr -d ' ')
    if [ -n "$published" ] && [[ ! "$published" =~ ^(true|false)$ ]]; then
        echo "ERROR: $file - 'published' must be true or false, got: $published"
        ((errors++))
    fi
    
    # Check date format (YYYY-MM-DD)
    date_val=$(echo "$frontmatter" | grep "^date:" | cut -d: -f2 | tr -d ' ')
    if [ -n "$date_val" ] && [[ ! "$date_val" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
        echo "WARNING: $file - Date format should be YYYY-MM-DD, got: $date_val"
    fi
done

if [ $errors -gt 0 ]; then
    echo ""
    echo "Found $errors frontmatter error(s)"
    exit 1
fi

echo "All frontmatter valid!"

Add the script to pre-commit:

repos:
  - repo: local
    hooks:
      - id: validate-frontmatter
        name: Validate Frontmatter
        entry: bash scripts/validate-frontmatter.sh
        language: system
        files: \.(md|markdown)$
        pass_filenames: true

Markdown Linting #

Consistent Markdown formatting improves maintainability and ensures reliable rendering.

Using markdownlint-cli #

repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.42.0
    hooks:
      - id: markdownlint
        args: [--config, .markdownlint.json, --fix]

Create .markdownlint.json:

{
  "default": true,
  
  "MD001": true,
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD007": { "indent": 2 },
  "MD009": { "br_spaces": 2 },
  "MD010": true,
  "MD012": { "maximum": 2 },
  
  "MD013": false,
  
  "MD022": { "lines_above": 1, "lines_below": 1 },
  "MD024": { "siblings_only": true },
  "MD025": { "front_matter_title": "^\\s*title\\s*[:=]" },
  
  "MD026": { "punctuation": ".,;:!" },
  
  "MD033": {
    "allowed_elements": [
      "details", "summary", "kbd", "br", "sup", "sub",
      "img", "video", "audio", "source", "iframe"
    ]
  },
  
  "MD034": true,
  
  "MD036": false,
  
  "MD040": true,
  "MD041": false,
  "MD046": { "style": "fenced" },
  "MD048": { "style": "backtick" }
}

Rule Reference #

Common rules you may want to configure:

Rule	Description	Recommended
MD013	Line length	Disable for prose
MD033	No inline HTML	Allow specific tags
MD041	First line H1	Disable (frontmatter)
MD025	Single H1	Enable with frontmatter exception
MD024	No duplicate headings	Enable siblings only

Per-File Overrides #

Disable rules for specific files using .markdownlintignore:

# .markdownlintignore
# Ignore generated files
public/
node_modules/

# Ignore specific files
CHANGELOG.md

Or use inline comments in Markdown:

<!-- markdownlint-disable MD033 -->
<details>
<summary>Click to expand</summary>

Content here...

</details>
<!-- markdownlint-enable MD033 -->

Link Checking #

Broken links hurt user experience and SEO. Check links before committing.

Using markdown-link-check #

repos:
  - repo: https://github.com/tcort/markdown-link-check
    rev: v3.12.2
    hooks:
      - id: markdown-link-check
        args: [--config, .markdown-link-check.json]

Create .markdown-link-check.json:

{
  "ignorePatterns": [
    { "pattern": "^https://localhost" },
    { "pattern": "^https://127\\.0\\.0\\.1" },
    { "pattern": "^#" }
  ],
  "replacementPatterns": [
    {
      "pattern": "^/",
      "replacement": "{{BASEURL}}/"
    }
  ],
  "httpHeaders": [
    {
      "urls": ["https://github.com"],
      "headers": {
        "Accept": "text/html"
      }
    }
  ],
  "timeout": "10s",
  "retryOn429": true,
  "retryCount": 3,
  "fallbackRetryDelay": "5s",
  "aliveStatusCodes": [200, 206, 301, 302, 307, 308]
}

Using lychee (Faster Alternative) #

lychee is a fast, async link checker written in Rust:

repos:
  - repo: local
    hooks:
      - id: lychee
        name: Check links with lychee
        entry: lychee
        language: system
        files: \.(md|html)$
        args:
          - --config=.lychee.toml
          - --no-progress

Create .lychee.toml:

# .lychee.toml

# Maximum number of concurrent requests
max_concurrency = 32

# Timeout for requests
timeout = 20

# User agent
user_agent = "lychee/0.15"

# Accept codes
accept = [200, 204, 301, 302, 307, 308]

# Exclude patterns
exclude = [
    "^https://localhost",
    "^https://127\\.0\\.0\\.1",
    "^mailto:",
    "^tel:",
]

# Exclude paths
exclude_path = [
    "node_modules",
    "public",
    ".git",
]

# Skip private IPs
skip_missing = false

# Include fragments
include_fragments = true

Link Checking Best Practices #

Cache results - Link checking is slow; cache in CI
Allow retries - Some sites rate-limit requests
Exclude known-good patterns - Skip localhost, anchors
Run separately - Consider running link checks only in CI, not on every commit

Image Alt Text Validation #

Alt text is essential for accessibility. Validate that all images have meaningful descriptions.

Custom Alt Text Checker #

#!/bin/bash
# scripts/check-alt-text.sh
# Ensures all images have alt text

set -e

errors=0

for file in "$@"; do
    [[ "$file" != *.md ]] && continue
    
    # Find images without alt text: ![](url) or ![ ](url)
    # Correct format: ![alt text](url)
    
    # Check for empty alt text
    if grep -Pn '!\[\s*\]\(' "$file"; then
        echo "ERROR: $file - Found image(s) with empty alt text"
        ((errors++))
    fi
    
    # Check for placeholder alt text
    if grep -Pin '!\[(image|img|photo|picture|screenshot)\]\(' "$file"; then
        echo "WARNING: $file - Found image(s) with placeholder alt text"
    fi
done

if [ $errors -gt 0 ]; then
    echo ""
    echo "Found $errors image(s) missing alt text"
    echo "Add descriptive alt text: ![description of image](url)"
    exit 1
fi

echo "All images have alt text!"

Add to pre-commit:

repos:
  - repo: local
    hooks:
      - id: check-alt-text
        name: Check image alt text
        entry: bash scripts/check-alt-text.sh
        language: system
        files: \.(md|markdown)$
        pass_filenames: true

Using remark-lint #

For more comprehensive Markdown validation including alt text:

repos:
  - repo: local
    hooks:
      - id: remark-lint
        name: Remark lint
        entry: npx remark
        language: node
        files: \.(md|markdown)$
        args: [--frail, --quiet]
        additional_dependencies:
          - remark-cli
          - remark-preset-lint-recommended
          - remark-lint-no-empty-image-alt

Create .remarkrc.js:

// .remarkrc.js
module.exports = {
  plugins: [
    'preset-lint-recommended',
    'lint-no-empty-image-alt',
    ['lint-no-undefined-references', false], // Allow [[wikilinks]]
  ],
};

Custom Validation Scripts #

Validate Slug Uniqueness #

Prevent duplicate slugs that cause build conflicts:

#!/bin/bash
# scripts/check-unique-slugs.sh

set -e

# Extract all slugs from frontmatter
declare -A slugs

for file in $(find . -name "*.md" -not -path "./node_modules/*" -not -path "./public/*"); do
    slug=$(sed -n '/^---$/,/^---$/p' "$file" | grep "^slug:" | cut -d: -f2- | tr -d ' "'"'"'')
    
    if [ -n "$slug" ]; then
        if [ -n "${slugs[$slug]}" ]; then
            echo "ERROR: Duplicate slug '$slug'"
            echo "  - ${slugs[$slug]}"
            echo "  - $file"
            exit 1
        fi
        slugs[$slug]="$file"
    fi
done

echo "All slugs are unique!"

Validate Tags #

Ensure consistent tag usage:

#!/bin/bash
# scripts/validate-tags.sh

# Allowed tags (customize for your site)
allowed_tags=(
    "documentation"
    "tutorial"
    "guide"
    "reference"
    "blog"
    "announcement"
)

errors=0

for file in "$@"; do
    [[ "$file" != *.md ]] && continue
    
    # Extract tags from frontmatter
    tags=$(sed -n '/^tags:/,/^[a-z]/p' "$file" | grep "^\s*-" | sed 's/^\s*-\s*//')
    
    while IFS= read -r tag; do
        tag=$(echo "$tag" | tr -d ' ')
        [ -z "$tag" ] && continue
        
        if [[ ! " ${allowed_tags[*]} " =~ " ${tag} " ]]; then
            echo "WARNING: $file - Unknown tag: $tag"
            echo "  Allowed tags: ${allowed_tags[*]}"
        fi
    done <<< "$tags"
done

exit 0  # Warnings only, don't block commit

Check Required Sections #

Ensure documentation has required sections:

#!/bin/bash
# scripts/check-doc-structure.sh

for file in "$@"; do
    [[ "$file" != docs/*.md ]] && continue
    
    # Check for table of contents
    if ! grep -q "## Table of Contents" "$file"; then
        echo "WARNING: $file - Missing Table of Contents"
    fi
    
    # Check for See Also section
    if ! grep -q "## See Also" "$file"; then
        echo "INFO: $file - Consider adding a See Also section"
    fi
done

Complete Configuration Example #

Here’s a comprehensive .pre-commit-config.yaml for a markata-go site:

# .pre-commit-config.yaml
# Complete content quality configuration for markata-go sites

default_language_version:
  python: python3

repos:
  # ============================================
  # Basic file checks
  # ============================================
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
        args: [--markdown-linebreak-ext=md]
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-toml
      - id: check-added-large-files
        args: [--maxkb=1024]
      - id: mixed-line-ending
        args: [--fix=lf]
      - id: check-merge-conflict
      - id: detect-private-key

  # ============================================
  # YAML/Frontmatter validation
  # ============================================
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [--config-file, .yamllint.yml]
        files: \.(md|yaml|yml)$

  # ============================================
  # Markdown linting
  # ============================================
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.42.0
    hooks:
      - id: markdownlint
        args: [--config, .markdownlint.json, --fix]
        exclude: ^(CHANGELOG|node_modules/)

  # ============================================
  # Link checking (optional - can be slow)
  # ============================================
  # - repo: https://github.com/tcort/markdown-link-check
  #   rev: v3.12.2
  #   hooks:
  #     - id: markdown-link-check
  #       args: [--config, .markdown-link-check.json]

  # ============================================
  # Custom validations
  # ============================================
  - repo: local
    hooks:
      # Validate required frontmatter fields
      - id: validate-frontmatter
        name: Validate Frontmatter
        entry: bash scripts/validate-frontmatter.sh
        language: system
        files: \.(md|markdown)$
        pass_filenames: true

      # Check image alt text
      - id: check-alt-text
        name: Check image alt text
        entry: bash scripts/check-alt-text.sh
        language: system
        files: \.(md|markdown)$
        pass_filenames: true

      # Validate build (optional - can be slow)
      # - id: markata-build
      #   name: Test build
      #   entry: markata-go build --dry-run
      #   language: system
      #   pass_filenames: false
      #   stages: [push]

Directory Structure #

After setup, your project should have:

your-site/
├── .pre-commit-config.yaml     # Pre-commit configuration
├── .yamllint.yml               # YAML linting rules
├── .markdownlint.json          # Markdown linting rules
├── .markdown-link-check.json   # Link checker config (optional)
├── scripts/
│   ├── validate-frontmatter.sh
│   └── check-alt-text.sh
├── docs/
│   └── ...your content...
└── markata-go.toml

Troubleshooting #

Common Issues #

Hook not running

# Reinstall hooks
pre-commit uninstall
pre-commit install

Skipping hooks temporarily

# Skip all hooks (use sparingly!)
git commit --no-verify -m "WIP: work in progress"

# Skip specific hook
SKIP=markdownlint git commit -m "Quick fix"

Hooks too slow

# Run only on changed files (default behavior)
pre-commit run

# Cache is stored in ~/.cache/pre-commit/

False positives

Use inline comments to disable specific rules:

<!-- markdownlint-disable MD033 -->
<custom-element>content</custom-element>
<!-- markdownlint-enable MD033 -->

Or exclude files in .markdownlintignore.

Quality Assurance Guide

2026-01-24T00:00:00Z

Quality Assurance for Your markata-go Site #

Maintaining high-quality content is essential for any professional site. This guide covers tools and practices for validating frontmatter, linting Markdown, checking links, and ensuring accessibility in your markata-go site.

Table of Contents #

Why Quality Assurance? #

Content quality issues can harm your site in several ways:

Issue	Impact
Invalid frontmatter	Build failures, missing metadata
Broken links	Poor user experience, SEO penalties
Inconsistent Markdown	Rendering issues, maintenance burden
Missing alt text	Accessibility violations, SEO impact
YAML syntax errors	Build failures, data loss

Automated quality checks catch these issues before they reach production.

Quick Setup #

Get started with content quality checks in under 5 minutes:

1. Install pre-commit #

# macOS
brew install pre-commit

# pip (all platforms)
pip install pre-commit

2. Create Configuration #

Create .pre-commit-config.yaml in your site root:

repos:
  # YAML/Frontmatter validation
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [--config-file, .yamllint.yml]
        types: [markdown]

  # Markdown linting
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.42.0
    hooks:
      - id: markdownlint
        args: [--config, .markdownlint.json]

3. Add Linter Configs #

Create .yamllint.yml:

extends: relaxed
rules:
  line-length: disable
  document-start: disable

Create .markdownlint.json:

{
  "MD013": false,
  "MD033": false,
  "MD041": false
}

4. Install and Run #

pre-commit install
pre-commit run --all-files

Now every commit will automatically validate your content!

Guide Sections #

This quality assurance documentation is organized into the following sections:

Pre-commit Hooks #

Set up automated checks that run before every commit:

YAML frontmatter validation
Markdown linting with markdownlint
Link checking
Image alt text validation
Custom validation scripts

GitHub Actions #

Continuous integration workflows for GitHub:

Build validation on pull requests
Link checking across your entire site
Content quality gates
Automated reporting

GitLab CI #

CI/CD pipelines for GitLab:

Pipeline configuration
Caching for faster builds
Merge request quality gates
Badge generation

Custom Rules #

Configure linting rules for your specific needs:

markdownlint rule customization
Custom frontmatter validation
Project-specific style guides
Rule inheritance and overrides

Troubleshooting #

Common issues and solutions:

False positives and how to handle them
Performance optimization
Integration debugging
Migration from other tools

Editor Integration #

Use lint output with your editor’s quickfix features:

Vim/Neovim quickfix integration
VS Code problem matchers
Emacs compile-mode
Sublime Text build systems

Recommended Tool Stack #

Here’s the recommended set of tools for comprehensive content quality assurance:

Essential Tools #

Tool	Purpose	Installation
pre-commit	Git hooks framework	`pip install pre-commit`
markdownlint-cli	Markdown linting	`npm install -g markdownlint-cli`
yamllint	YAML validation	`pip install yamllint`

Recommended Additions #

Tool	Purpose	Installation
lychee	Fast link checking	`cargo install lychee`
htmltest	HTML validation	`go install github.com/wjdp/htmltest@latest`
pa11y	Accessibility testing	`npm install -g pa11y`

CI-Specific Tools #

Tool	Purpose	Platform
actionlint	GitHub Actions validation	GitHub
super-linter	Multi-language linting	GitHub

Next Steps #

Start with pre-commit hooks - They provide immediate feedback during development
Add CI checks - Ensure quality gates in your pull request workflow
Customize rules - Adjust linting rules to match your style guide
Monitor and iterate - Review false positives and refine your configuration

Choose your next section based on your development workflow:

Using Git locally? Start with Pre-commit Hooks
Using GitHub? Jump to GitHub Actions
Using GitLab? See GitLab CI

GitLab CI for Content Quality

2026-01-24T00:00:00Z

GitLab CI/CD provides powerful pipeline capabilities for validating your markata-go site content. This guide covers pipeline configuration, caching strategies, merge request quality gates, and badge generation.

Table of Contents #

Quick Start #

Create .gitlab-ci.yml in your repository root:

stages:
  - lint
  - build
  - test

lint:
  stage: lint
  image: python:3.12-slim
  before_script:
    - pip install yamllint
    - apt-get update && apt-get install -y nodejs npm
    - npm install -g markdownlint-cli
  script:
    - markdownlint '**/*.md' --ignore node_modules --ignore public
    - |
      for file in $(find . -name "*.md" -not -path "./node_modules/*"); do
        frontmatter=$(sed -n '1,/^---$/p' "$file" | tail -n +2 | head -n -1)
        if [ -n "$frontmatter" ]; then
          echo "$frontmatter" | yamllint -d relaxed -
        fi
      done
  rules:
    - changes:
        - "**/*.md"

Basic Pipeline Configuration #

Pipeline Structure #

# .gitlab-ci.yml
stages:
  - lint        # Fast checks
  - build       # Build site
  - test        # Post-build validation
  - deploy      # Deploy to production

variables:
  SITE_URL: https://example.com
  GO_VERSION: "1.22"

default:
  image: golang:${GO_VERSION}-alpine
  before_script:
    - go install github.com/waylonwalker/markata-go/cmd/markata-go@latest

Environment Variables #

Configure these variables in GitLab Settings > CI/CD > Variables:

Variable	Description	Example
`SITE_URL`	Production site URL	`https://example.com`
`DEPLOY_TOKEN`	Deployment credentials	`glpat-xxx`
`SLACK_WEBHOOK`	Notifications URL	`https://hooks.slack.com/...`

Build Validation Pipeline #

Basic Build Job #

# .gitlab-ci.yml
stages:
  - lint
  - build

variables:
  GO_VERSION: "1.22"

build:
  stage: build
  image: golang:${GO_VERSION}-alpine
  
  before_script:
    - go install github.com/waylonwalker/markata-go/cmd/markata-go@latest
  
  script:
    - markata-go config validate
    - markata-go build --clean
  
  artifacts:
    paths:
      - public/
    expire_in: 1 week
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Build with Environment-Specific URLs #

build:
  stage: build
  image: golang:1.22-alpine
  
  before_script:
    - go install github.com/waylonwalker/markata-go/cmd/markata-go@latest
  
  script:
    - markata-go build --clean
  
  variables:
    MARKATA_GO_URL: >-
      ${CI_MERGE_REQUEST_IID:+https://preview-${CI_MERGE_REQUEST_IID}.example.com}
      ${CI_MERGE_REQUEST_IID:-https://example.com}
  
  artifacts:
    paths:
      - public/
    expire_in: 1 week

Link Checking Pipeline #

Using lychee #

check-links:
  stage: test
  image: lycheeverse/lychee:latest
  needs: [build]
  
  script:
    - |
      lychee \
        --verbose \
        --no-progress \
        --accept 200,204,301,302,307,308 \
        --timeout 30 \
        --max-retries 3 \
        --exclude-path node_modules \
        --exclude-path .git \
        --exclude 'localhost' \
        --exclude '127\.0\.0\.1' \
        --exclude 'mailto:' \
        './public/**/*.html'
  
  allow_failure: true
  
  artifacts:
    reports:
      junit: lychee-report.xml
    when: always
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "schedule"

Scheduled Link Checks #

Add to your pipeline for weekly link rot detection:

check-external-links:
  stage: test
  image: lycheeverse/lychee:latest
  
  script:
    - |
      lychee \
        --verbose \
        --include-mail \
        --timeout 60 \
        --max-retries 5 \
        './public/**/*.html' || true
    
    # Create issue if links are broken
    - |
      if [ -f lychee/out.md ] && [ -s lychee/out.md ]; then
        echo "Broken links detected. See artifacts for details."
        exit 1
      fi
  
  artifacts:
    paths:
      - lychee/
    expire_in: 1 month
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Configure a scheduled pipeline in GitLab Settings > CI/CD > Schedules:

Description: “Weekly link check”
Interval: 0 0 * * 0 (weekly on Sunday)
Target branch: main

Content Quality Gates #

Comprehensive Linting Job #

lint:
  stage: lint
  image: python:3.12-slim
  
  before_script:
    - pip install yamllint
    - apt-get update && apt-get install -y nodejs npm
    - npm install -g markdownlint-cli
  
  script:
    # Markdown linting
    - markdownlint '**/*.md' --ignore node_modules --ignore public --config .markdownlint.json
    
    # YAML frontmatter validation
    - |
      for file in $(find . -name "*.md" -not -path "./node_modules/*" -not -path "./public/*"); do
        echo "Checking: $file"
        frontmatter=$(sed -n '1,/^---$/p' "$file" | tail -n +2 | head -n -1)
        if [ -n "$frontmatter" ]; then
          echo "$frontmatter" | yamllint -c .yamllint.yml - || exit 1
        fi
      done
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

frontmatter-validation:
  stage: lint
  image: alpine:latest
  
  script:
    - |
      errors=0
      for file in $(find docs -name "*.md" 2>/dev/null); do
        for field in title date published; do
          if ! grep -q "^${field}:" "$file"; then
            echo "ERROR: $file - Missing required field: $field"
            errors=$((errors + 1))
          fi
        done
      done
      
      if [ $errors -gt 0 ]; then
        echo "Found $errors frontmatter errors"
        exit 1
      fi
      echo "All frontmatter valid!"
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

alt-text-check:
  stage: lint
  image: alpine:latest
  
  script:
    - |
      errors=0
      for file in $(find . -name "*.md" -not -path "./node_modules/*"); do
        if grep -Pn '!\[\s*\]\(' "$file"; then
          echo "ERROR: $file - Found image(s) without alt text"
          errors=$((errors + 1))
        fi
      done
      
      if [ $errors -gt 0 ]; then
        echo "Found $errors images missing alt text"
        exit 1
      fi
      echo "All images have alt text!"
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

Spell Checking #

spellcheck:
  stage: lint
  image: rust:latest
  
  before_script:
    - cargo install typos-cli
  
  script:
    - typos ./docs --config .typos.toml
  
  allow_failure: true
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

Complete Quality Pipeline #

A comprehensive pipeline that runs all quality checks:

# .gitlab-ci.yml
# Complete content quality pipeline for markata-go sites

stages:
  - lint
  - build
  - test
  - deploy

variables:
  GO_VERSION: "1.22"
  NODE_VERSION: "20"
  SITE_URL: https://example.com

# ============================================
# Templates for reuse
# ============================================

.go-setup:
  image: golang:${GO_VERSION}-alpine
  before_script:
    - go install github.com/waylonwalker/markata-go/cmd/markata-go@latest

.node-setup:
  image: node:${NODE_VERSION}-alpine
  before_script:
    - npm install -g markdownlint-cli

.python-setup:
  image: python:3.12-slim
  before_script:
    - pip install yamllint

# ============================================
# Stage 1: Lint (parallel jobs)
# ============================================

markdown-lint:
  extends: .node-setup
  stage: lint
  
  script:
    - markdownlint '**/*.md' --ignore node_modules --ignore public --config .markdownlint.json
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

yaml-lint:
  extends: .python-setup
  stage: lint
  
  script:
    - yamllint -c .yamllint.yml .
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"
        - "**/*.yml"
        - "**/*.yaml"

frontmatter:
  stage: lint
  image: alpine:latest
  
  script:
    - |
      errors=0
      for file in $(find docs -name "*.md" 2>/dev/null || true); do
        for field in title date published; do
          if ! grep -q "^${field}:" "$file" 2>/dev/null; then
            echo "ERROR: $file - Missing: $field"
            errors=$((errors + 1))
          fi
        done
      done
      [ $errors -eq 0 ] || exit 1
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

# ============================================
# Stage 2: Build
# ============================================

build:
  extends: .go-setup
  stage: build
  needs: [markdown-lint, yaml-lint, frontmatter]
  
  script:
    - markata-go config validate
    - markata-go build --clean
  
  variables:
    MARKATA_GO_URL: $SITE_URL
  
  artifacts:
    paths:
      - public/
    expire_in: 1 week
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ============================================
# Stage 3: Test (post-build validation)
# ============================================

html-validate:
  stage: test
  image: node:${NODE_VERSION}-alpine
  needs: [build]
  
  before_script:
    - npm install -g html-validate
  
  script:
    - html-validate "public/**/*.html" --config .htmlvalidate.json || true
  
  allow_failure: true
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

check-links:
  stage: test
  image: lycheeverse/lychee:latest
  needs: [build]
  
  script:
    - |
      lychee \
        --verbose \
        --no-progress \
        --accept 200,204,301,302,307,308 \
        --exclude-path node_modules \
        --exclude 'localhost' \
        './public/**/*.html'
  
  allow_failure: true
  
  artifacts:
    paths:
      - lychee/
    when: always
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ============================================
# Stage 4: Deploy
# ============================================

pages:
  stage: deploy
  needs: [build, html-validate, check-links]
  
  script:
    - echo "Deploying to GitLab Pages"
  
  artifacts:
    paths:
      - public/
  
  environment:
    name: production
    url: $SITE_URL
  
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Caching Strategies #

Speed up your pipelines with effective caching.

Go Module Cache #

variables:
  GOPATH: $CI_PROJECT_DIR/.go

build:
  stage: build
  image: golang:1.22-alpine
  
  cache:
    key: go-modules-$CI_COMMIT_REF_SLUG
    paths:
      - .go/pkg/mod/
    policy: pull-push
  
  script:
    - go install github.com/waylonwalker/markata-go/cmd/markata-go@latest
    - markata-go build --clean

Node.js Cache #

lint:
  stage: lint
  image: node:20-alpine
  
  cache:
    key: node-modules-$CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
    policy: pull-push
  
  script:
    - npm install markdownlint-cli
    - npx markdownlint '**/*.md'

Combined Cache Strategy #

variables:
  GOPATH: $CI_PROJECT_DIR/.go
  npm_config_cache: $CI_PROJECT_DIR/.npm

default:
  cache:
    - key: go-$CI_COMMIT_REF_SLUG
      paths:
        - .go/pkg/mod/
      policy: pull-push
    - key: npm-$CI_COMMIT_REF_SLUG
      paths:
        - .npm/
      policy: pull-push

Merge Request Integration #

Merge Request Pipelines #

Configure pipelines to run on merge requests:

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "schedule"

lint:
  stage: lint
  script:
    - echo "Running lint checks"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.md"

Merge Request Comments #

Report quality issues directly in merge request comments:

report-quality:
  stage: test
  image: alpine:latest
  needs: [lint, build]
  
  script:
    - |
      # Collect lint results
      if [ -f lint-results.json ]; then
        echo "## Content Quality Report" > report.md
        echo "" >> report.md
        echo "### Linting Results" >> report.md
        cat lint-results.json | jq -r '.[] | "- \(.file): \(.message)"' >> report.md
      fi
    
    # Post comment to MR
    - |
      if [ -f report.md ]; then
        curl --request POST \
          --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
          --form "body=$(cat report.md)" \
          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes"
      fi
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Required Approvals #

Configure merge request approval rules in GitLab Settings > Merge Requests:

Require pipeline to succeed before merging
Set required approvals for content changes
Configure code owners for documentation directories

Example CODEOWNERS file:

# .gitlab/CODEOWNERS
docs/       @docs-team
*.md        @docs-team @content-reviewers

Badge Generation #

Add status badges to your README.

Pipeline Status Badge #

[![Pipeline Status](https://gitlab.com/username/repo/badges/main/pipeline.svg)](https://gitlab.com/username/repo/-/pipelines)

Coverage Badge (if applicable) #

[![Coverage](https://gitlab.com/username/repo/badges/main/coverage.svg)](https://gitlab.com/username/repo/-/jobs)

Custom Badges #

Generate custom badges for quality metrics:

generate-badges:
  stage: deploy
  image: alpine:latest
  
  script:
    # Count markdown files
    - file_count=$(find docs -name "*.md" | wc -l)
    
    # Generate badge JSON for shields.io
    - |
      cat > public/badges/docs-count.json << EOF
      {
        "schemaVersion": 1,
        "label": "docs",
        "message": "${file_count} pages",
        "color": "blue"
      }
      EOF
  
  artifacts:
    paths:
      - public/badges/
  
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Use with shields.io:

![Docs Count](https://img.shields.io/endpoint?url=https://example.com/badges/docs-count.json)

GitLab Pages Deployment #

Basic Pages Deployment #

pages:
  stage: deploy
  
  script:
    - echo "Deploying to GitLab Pages"
  
  artifacts:
    paths:
      - public/
  
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Pages with Review Apps #

Deploy preview environments for merge requests:

pages:review:
  stage: deploy
  needs: [build]
  
  script:
    - echo "Deploying review app"
  
  artifacts:
    paths:
      - public/
  
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html
    on_stop: stop:review
    auto_stop_in: 1 week
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

stop:review:
  stage: deploy
  
  script:
    - echo "Stopping review app"
  
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

Troubleshooting #

Common Issues #

Pipeline not triggering on MR

Ensure workflow rules are configured:

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Cache not working

Check cache key and paths:

cache:
  key: $CI_COMMIT_REF_SLUG  # Use branch-specific keys
  paths:
    - .go/pkg/mod/
  policy: pull-push  # Ensure both pull and push

Job stuck in pending

Check runner availability and tags:

build:
  tags:
    - docker  # Match available runners

Artifacts not available in downstream jobs

Use needs to explicitly depend on artifacts:

deploy:
  needs:
    - job: build
      artifacts: true

GitHub Actions for Content Quality

2026-01-24T00:00:00Z

GitHub Actions provides powerful CI/CD capabilities for validating your markata-go site content. This guide covers workflows for build validation, link checking, and content quality gates.

Table of Contents #

Quick Start #

Create .github/workflows/content-quality.yml:

name: Content Quality

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown
        uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          globs: |
            **/*.md
            !node_modules
            !public

      - name: Check YAML frontmatter
        run: |
          pip install yamllint
          find . -name "*.md" -exec grep -l "^---" {} \; | \
            xargs -I {} sh -c 'sed -n "/^---$/,/^---$/p" {} | yamllint -'

Build Validation Workflow #

Ensure your site builds successfully on every push and pull request.

Basic Build Check #

# .github/workflows/build.yml
name: Build Validation

on:
  push:
    branches: [main]
    paths:
      - '**.md'
      - '**.toml'
      - 'templates/**'
      - 'static/**'
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Install markata-go
        run: go install github.com/waylonwalker/markata-go/cmd/markata-go@latest

      - name: Validate config
        run: markata-go config validate

      - name: Build site
        run: markata-go build --clean
        env:
          MARKATA_GO_URL: ${{ github.event_name == 'pull_request' && format('https://preview-{0}.example.com', github.event.number) || 'https://example.com' }}

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: site-build
          path: public/
          retention-days: 7

Build with Cache #

Speed up builds by caching Go modules and the markata-go binary:

# .github/workflows/build-cached.yml
name: Build (Cached)

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Cache markata-go binary
        uses: actions/cache@v4
        id: markata-cache
        with:
          path: ~/go/bin/markata-go
          key: markata-go-${{ runner.os }}-${{ hashFiles('go.sum') }}
          restore-keys: |
            markata-go-${{ runner.os }}-

      - name: Install markata-go
        if: steps.markata-cache.outputs.cache-hit != 'true'
        run: go install github.com/waylonwalker/markata-go/cmd/markata-go@latest

      - name: Build
        run: ~/go/bin/markata-go build --clean

Link Checking Workflow #

Check for broken links across your entire site.

Using lychee (Recommended) #

lychee is fast and handles many edge cases:

# .github/workflows/links.yml
name: Link Checker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Run weekly to catch external link rot
    - cron: '0 0 * * 0'

jobs:
  check-links:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Install and build
        run: |
          go install github.com/waylonwalker/markata-go/cmd/markata-go@latest
          markata-go build --clean
        env:
          MARKATA_GO_URL: https://example.com

      - name: Check links
        uses: lycheeverse/lychee-action@v1
        with:
          args: >-
            --verbose
            --no-progress
            --accept 200,204,301,302,307,308
            --timeout 30
            --max-retries 3
            --exclude-path node_modules
            --exclude-path .git
            --exclude 'https://localhost.*'
            --exclude 'https://127\.0\.0\.1.*'
            --exclude 'mailto:.*'
            './public/**/*.html'
          fail: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create issue on failure
        if: failure() && github.event_name == 'schedule'
        uses: peter-evans/create-issue-from-file@v5
        with:
          title: Broken links detected
          content-filepath: ./lychee/out.md
          labels: bug, documentation

Using markdown-link-check #

For checking Markdown files directly (without building):

# .github/workflows/markdown-links.yml
name: Markdown Link Check

on:
  push:
    branches: [main]
    paths: ['**.md']
  pull_request:
    branches: [main]
    paths: ['**.md']

jobs:
  check-links:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Check Markdown links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          config-file: '.markdown-link-check.json'
          use-quiet-mode: 'yes'
          use-verbose-mode: 'yes'
          folder-path: 'docs/'
          file-extension: '.md'

Link Check Configuration #

Create .markdown-link-check.json:

{
  "ignorePatterns": [
    { "pattern": "^https://localhost" },
    { "pattern": "^https://127\\.0\\.0\\.1" },
    { "pattern": "^#" },
    { "pattern": "^mailto:" }
  ],
  "replacementPatterns": [
    {
      "pattern": "^/docs/",
      "replacement": "https://example.com/docs/"
    }
  ],
  "httpHeaders": [
    {
      "urls": ["https://github.com", "https://api.github.com"],
      "headers": {
        "Accept": "text/html, application/vnd.github.v3+json"
      }
    }
  ],
  "timeout": "20s",
  "retryOn429": true,
  "retryCount": 3,
  "fallbackRetryDelay": "10s",
  "aliveStatusCodes": [200, 206, 301, 302, 307, 308]
}

Content Quality Gates #

Enforce quality standards before merging pull requests.

Comprehensive Linting #

# .github/workflows/lint.yml
name: Content Lint

on:
  pull_request:
    branches: [main]
    paths: ['**.md']

jobs:
  markdown-lint:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown files
        uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          config: .markdownlint.json
          globs: |
            **/*.md
            !node_modules/**
            !public/**

  yaml-lint:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install yamllint
        run: pip install yamllint

      - name: Lint YAML frontmatter
        run: |
          for file in $(find . -name "*.md" -not -path "./node_modules/*" -not -path "./public/*"); do
            echo "Checking: $file"
            # Extract frontmatter and lint it
            frontmatter=$(sed -n '1,/^---$/p' "$file" | tail -n +2 | head -n -1)
            if [ -n "$frontmatter" ]; then
              echo "$frontmatter" | yamllint -c .yamllint.yml -
            fi
          done

  frontmatter-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Check required frontmatter
        run: |
          errors=0
          for file in $(find docs -name "*.md"); do
            # Check for required fields
            for field in title date published; do
              if ! grep -q "^${field}:" "$file"; then
                echo "::error file=$file::Missing required field: $field"
                errors=$((errors + 1))
              fi
            done
          done
          exit $errors

  alt-text-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Check image alt text
        run: |
          errors=0
          for file in $(find . -name "*.md" -not -path "./node_modules/*"); do
            # Find images with empty alt text
            if grep -Pn '!\[\s*\]\(' "$file"; then
              echo "::error file=$file::Found image without alt text"
              errors=$((errors + 1))
            fi
          done
          exit $errors

Spell Checking #

# .github/workflows/spelling.yml
name: Spell Check

on:
  pull_request:
    branches: [main]
    paths: ['**.md']

jobs:
  spellcheck:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Check spelling
        uses: crate-ci/typos@master
        with:
          files: ./docs
          config: .typos.toml

Create .typos.toml:

# .typos.toml
[default.extend-words]
# Add custom words that aren't typos
markata = "markata"
frontmatter = "frontmatter"
goldmark = "goldmark"

[files]
extend-exclude = [
    "*.json",
    "*.toml",
    "public/",
    "node_modules/",
]

Complete Quality Pipeline #

A comprehensive workflow that runs all quality checks:

# .github/workflows/quality.yml
name: Content Quality Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ============================================
  # Stage 1: Fast checks (run in parallel)
  # ============================================
  
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          config: .markdownlint.json
          globs: '**/*.md'

  yaml-lint:
    name: YAML Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install yamllint
      - run: yamllint -c .yamllint.yml .

  frontmatter:
    name: Frontmatter Validation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate frontmatter
        run: |
          errors=0
          for file in $(find docs -name "*.md" 2>/dev/null || true); do
            for field in title date published; do
              if ! grep -q "^${field}:" "$file" 2>/dev/null; then
                echo "::error file=$file::Missing: $field"
                errors=$((errors + 1))
              fi
            done
          done
          [ $errors -eq 0 ] || exit 1

  spelling:
    name: Spell Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: crate-ci/typos@master

  # ============================================
  # Stage 2: Build (depends on lint)
  # ============================================
  
  build:
    name: Build Site
    needs: [markdown-lint, yaml-lint, frontmatter]
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Install markata-go
        run: go install github.com/waylonwalker/markata-go/cmd/markata-go@latest

      - name: Build site
        run: markata-go build --clean
        env:
          MARKATA_GO_URL: https://example.com

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: public/

  # ============================================
  # Stage 3: Post-build checks
  # ============================================
  
  html-validate:
    name: HTML Validation
    needs: build
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Download build
        uses: actions/download-artifact@v4
        with:
          name: site
          path: public/

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install html-validate
        run: npm install -g html-validate

      - name: Validate HTML
        run: |
          html-validate "public/**/*.html" --config .htmlvalidate.json || true
        continue-on-error: true

  links:
    name: Link Check
    needs: build
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Download build
        uses: actions/download-artifact@v4
        with:
          name: site
          path: public/

      - name: Check links
        uses: lycheeverse/lychee-action@v1
        with:
          args: >-
            --verbose
            --no-progress
            --accept 200,204,301,302,307,308
            --exclude-path node_modules
            --exclude 'localhost'
            './public/**/*.html'
          fail: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # ============================================
  # Stage 4: Deploy (only on main)
  # ============================================
  
  deploy:
    name: Deploy
    needs: [build, html-validate, links]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    
    permissions:
      contents: read
      pages: write
      id-token: write
    
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    steps:
      - name: Download build
        uses: actions/download-artifact@v4
        with:
          name: site
          path: public/

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload to Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: public/

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

HTML Validation Config #

Create .htmlvalidate.json:

{
  "extends": ["html-validate:recommended"],
  "rules": {
    "no-trailing-whitespace": "off",
    "void-style": "off",
    "attribute-boolean-style": "off"
  }
}

Reusable Workflows #

Create reusable workflows for consistency across multiple repositories.

Reusable Quality Check #

# .github/workflows/reusable-quality.yml
name: Reusable Quality Check

on:
  workflow_call:
    inputs:
      site-url:
        description: 'Site URL for build'
        required: true
        type: string
      node-version:
        description: 'Node.js version'
        required: false
        type: string
        default: '20'

jobs:
  quality:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}

      - name: Install tools
        run: |
          go install github.com/waylonwalker/markata-go/cmd/markata-go@latest
          npm install -g markdownlint-cli

      - name: Lint
        run: markdownlint '**/*.md' --ignore node_modules --ignore public

      - name: Build
        run: markata-go build --clean
        env:
          MARKATA_GO_URL: ${{ inputs.site-url }}

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: public/

Using the Reusable Workflow #

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  quality:
    uses: ./.github/workflows/reusable-quality.yml
    with:
      site-url: https://example.com

Status Badges #

Add status badges to your README:

# My Site

[![Content Quality](https://github.com/username/repo/actions/workflows/quality.yml/badge.svg)](https://github.com/username/repo/actions/workflows/quality.yml)
[![Links](https://github.com/username/repo/actions/workflows/links.yml/badge.svg)](https://github.com/username/repo/actions/workflows/links.yml)
[![Deploy](https://github.com/username/repo/actions/workflows/deploy.yml/badge.svg)](https://github.com/username/repo/actions/workflows/deploy.yml)

Editor Integration

2026-01-24T00:00:00Z

Use the Language Server Protocol (LSP) for live wikilink completions, broken-link diagnostics, hover details, and go-to-definition. Use markata-go lint when you also need content-quality checks in an editor’s quickfix or Problems panel.

Start With A Health Check #

From the root of your site, run:

markata-go lsp doctor

The command verifies the local binary and validates any discovered markata-go configuration. It does not modify your editor configuration. Your editor—not the configuration file—supplies the LSP workspace root.

It also detects supported editors installed on your PATH. For Neovim, Helix, and Emacs, it loads the editor configuration for a deeper check by default:

markata-go lsp doctor

This can run editor startup and plugin code. Skip it when needed while still detecting editors:

markata-go lsp doctor --no-verify-editor

The report labels each detected editor as configured, unconfigured, or inconclusive. VS Code, Cursor, and Zed are detected but do not have stable headless LSP verification APIs.

When verification is skipped and a headless-verifiable editor is detected, the report prints the default doctor follow-up command to stderr. This keeps the primary diagnostic report on stdout while making the next interactive action easy to spot.

In an interactive terminal, the report uses your configured site palette for pass, information, warning, and failure states. The textual labels remain present for accessibility and plain output.

Every LSP client uses the same stable values:

Setting	Value
Command	`markata-go lsp`
File type	Markdown
Workspace root	Directory containing `markata-go.toml` (or the site root)

Print a maintained starting snippet with:

markata-go lsp setup --editor neovim

Omit --editor to print snippets for every supported editor installed on your PATH:

markata-go lsp setup

When more than one editor is found, each snippet has a clear heading. Interactive terminal output is syntax highlighted; redirected output remains plain text for copying into configuration files.

Available editors are generic, neovim, helix, emacs, zed, and vscode. The command only prints guidance: it deliberately does not rewrite editor settings because editor versions, extensions, and configuration layouts vary. When using an agent, have it inspect the editor configuration already in the repository or home directory, then adapt the generated snippet.

Language Server Setup #

Neovim #

For Neovim 0.11 or later, add the output of this command to init.lua or a loaded Lua module:

markata-go lsp setup --editor neovim

Helix #

Append the generated TOML to ~/.config/helix/languages.toml:

markata-go lsp setup --editor helix

Restart Helix after changing the file.

Emacs #

With Eglot enabled, add the generated Elisp to your Emacs init file:

markata-go lsp setup --editor emacs

VS Code, Cursor, And Zed #

These editors need an installed LSP client or a Markata-aware extension before they can launch an arbitrary stdio language server. Print the required command, arguments, file type, and workspace-root values, then apply them using the configuration format required by the installed extension:

markata-go lsp setup --editor vscode
markata-go lsp setup --editor zed

Do not use an editor task as an LSP replacement: tasks run once and cannot provide completion, hover, or navigation.

Other Editors #

Use the generic contract when your editor is not listed:

markata-go lsp setup --editor generic

Configure the editor’s LSP client to launch markata-go lsp over standard I/O for Markdown documents. Use its native workspace-root setting to point at the site root.

Lint Integration #

The markata-go lint command outputs issues in a format compatible with many editors’ error navigation features. The remaining sections show how to integrate those checks with popular editors.

Vim / Neovim Quickfix #

Vim and Neovim have built-in quickfix support for navigating errors and warnings.

Basic Usage #

" Set markata-go as the make program
:set makeprg=markata-go\ lint

" Run lint and populate quickfix
:make docs/**/*.md

" Open quickfix window
:cwindow

" Navigate errors
:cnext      " Go to next error
:cprev      " Go to previous error
:cfirst     " Go to first error
:clast      " Go to last error

Custom Error Format #

For perfect parsing of markata-go lint output, add this to your ~/.vimrc or init.vim:

" Add markata-go lint error format
set errorformat+=%f:
set errorformat+=\ \ %tarning\ [line\ %l\\,\ col\ %c]:\ %m
set errorformat+=\ \ %trror\ [line\ %l\\,\ col\ %c]:\ %m

One-liner Command #

Quick way to run lint and populate quickfix:

:cgetexpr system('markata-go lint docs/**/*.md')
:cwindow

Neovim Lua Configuration #

For Neovim users with Lua config:

-- ~/.config/nvim/lua/lint.lua or init.lua

-- Function to run markata-go lint
local function markata_lint()
  vim.cmd('cgetexpr system("markata-go lint docs/**/*.md")')
  vim.cmd('cwindow')
end

-- Create a user command
vim.api.nvim_create_user_command('MarkataLint', markata_lint, {})

-- Optional: keybinding
vim.keymap.set('n', '<leader>ml', markata_lint, { desc = 'Run markata-go lint' })

Lint Current File #

To lint only the current file:

:cgetexpr system('markata-go lint ' . expand('%'))

Or in Lua:

local function lint_current_file()
  local file = vim.fn.expand('%')
  vim.cmd('cgetexpr system("markata-go lint ' .. file .. '")')
  vim.cmd('cwindow')
end

VS Code Integration #

VS Code can use tasks with problem matchers to integrate with markata-go lint.

Task Configuration #

Create .vscode/tasks.json in your project:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Lint Markdown",
      "type": "shell",
      "command": "markata-go lint docs/**/*.md",
      "group": "build",
      "problemMatcher": {
        "owner": "markata-go",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": [
          {
            "regexp": "^(.+):$",
            "file": 1
          },
          {
            "regexp": "^\\s+(warning|error)\\s+\\[line\\s+(\\d+),\\s+col\\s+(\\d+)\\]:\\s+(.+)$",
            "severity": 1,
            "line": 2,
            "column": 3,
            "message": 4,
            "loop": true
          }
        ]
      }
    },
    {
      "label": "Lint Current File",
      "type": "shell",
      "command": "markata-go lint ${file}",
      "group": "build",
      "problemMatcher": {
        "owner": "markata-go",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": [
          {
            "regexp": "^(.+):$",
            "file": 1
          },
          {
            "regexp": "^\\s+(warning|error)\\s+\\[line\\s+(\\d+),\\s+col\\s+(\\d+)\\]:\\s+(.+)$",
            "severity": 1,
            "line": 2,
            "column": 3,
            "message": 4,
            "loop": true
          }
        ]
      }
    }
  ]
}

Running the Task #

Press Ctrl+Shift+B (or Cmd+Shift+B on Mac)
Select “Lint Markdown” from the task list
Errors appear in the Problems panel
Click on errors to jump to the file and line

Keyboard Shortcut #

Add a keybinding in keybindings.json:

{
  "key": "ctrl+shift+l",
  "command": "workbench.action.tasks.runTask",
  "args": "Lint Markdown"
}

Emacs Integration #

Emacs can use compile-mode to run lint and navigate errors.

Basic Usage #

;; Run markata-go lint
M-x compile RET markata-go lint docs/**/*.md RET

;; Navigate errors
M-g n  ; next-error
M-g p  ; previous-error

Custom Compilation Regexp #

Add to your Emacs config:

(add-to-list 'compilation-error-regexp-alist-alist
             '(markata-go
               "^\\(.*\\):\n  \\(warning\\|error\\) \\[line \\([0-9]+\\), col \\([0-9]+\\)\\]: \\(.*\\)$"
               1 3 4 2))

(add-to-list 'compilation-error-regexp-alist 'markata-go)

Flycheck Integration #

For on-the-fly linting with Flycheck:

(flycheck-define-checker markata-go
  "A markdown linter using markata-go."
  :command ("markata-go" "lint" source)
  :error-patterns
  ((warning line-start (file-name) ":\n"
            "  warning [line " line ", col " column "]: " (message) line-end)
   (error line-start (file-name) ":\n"
          "  error [line " line ", col " column "]: " (message) line-end))
  :modes (markdown-mode gfm-mode))

(add-to-list 'flycheck-checkers 'markata-go)

Sublime Text Integration #

Create a build system for markata-go lint.

Build System Configuration #

Create Packages/User/markata-go.sublime-build:

{
  "cmd": ["markata-go", "lint", "$file"],
  "working_dir": "$project_path",
  "file_regex": "^(.+):\n  (warning|error) \\[line (\\d+), col (\\d+)\\]: (.*)$",
  "selector": "text.html.markdown"
}

Usage #

Open a Markdown file
Press Ctrl+B (or Cmd+B on Mac)
Use F4 / Shift+F4 to navigate errors

Tips and Best Practices #

Lint on Save #

Most editors support running commands on file save. Configure your editor to run markata-go lint on the current file when saving for immediate feedback.

Vim/Neovim autocommand:

augroup MarkataLint
  autocmd!
  autocmd BufWritePost *.md cgetexpr system('markata-go lint ' . expand('%'))
augroup END

VS Code setting (settings.json):

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.md$",
        "cmd": "markata-go lint ${file}"
      }
    ]
  }
}

Project-wide Lint #

For CI/CD or pre-commit hooks, lint all files:

markata-go lint

This uses the glob patterns from your markata-go.toml configuration.

Exit Codes #

The lint command uses standard exit codes:

Code	Meaning
0	No issues found
1	Issues found
2	Error running lint

Use these in scripts:

if markata-go lint; then
  echo "All good!"
else
  echo "Issues found, check the output"
fi

Custom Linting Rules

2026-01-24T00:00:00Z

This guide covers how to configure linting rules for your specific needs, including markdownlint customization, custom frontmatter validation, and creating project-specific style guides.

Table of Contents #

markdownlint Configuration #

Configuration File Formats #

markdownlint supports multiple configuration formats:

JSON (.markdownlint.json)

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["details", "summary", "kbd"]
  }
}

YAML (.markdownlint.yaml)

default: true
MD013: false
MD033:
  allowed_elements:
    - details
    - summary
    - kbd

JavaScript (.markdownlint.cjs)

module.exports = {
  default: true,
  MD013: false,
  MD033: {
    allowed_elements: ['details', 'summary', 'kbd'],
  },
};

Complete Rule Reference #

Here’s a comprehensive configuration covering all common rules:

{
  "default": true,

  "MD001": true,
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD005": true,
  "MD007": { "indent": 2, "start_indented": false },
  "MD009": { "br_spaces": 2, "list_item_empty_lines": false },
  "MD010": { "code_blocks": true, "spaces_per_tab": 2 },
  "MD011": true,
  "MD012": { "maximum": 2 },

  "MD013": {
    "line_length": 120,
    "heading_line_length": 80,
    "code_block_line_length": 120,
    "code_blocks": false,
    "tables": false
  },

  "MD014": true,

  "MD018": true,
  "MD019": true,
  "MD020": true,
  "MD021": true,
  "MD022": { "lines_above": 1, "lines_below": 1 },
  "MD023": true,
  "MD024": { "siblings_only": true },
  "MD025": { "level": 1, "front_matter_title": "^\\s*title\\s*[:=]" },
  "MD026": { "punctuation": ".,;:!" },
  "MD027": true,
  "MD028": true,

  "MD029": { "style": "ordered" },
  "MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 },
  "MD031": { "list_items": true },
  "MD032": true,

  "MD033": {
    "allowed_elements": [
      "a", "abbr", "audio", "b", "br", "caption",
      "cite", "code", "col", "colgroup", "dd", "del",
      "details", "dfn", "div", "dl", "dt", "em",
      "figcaption", "figure", "h1", "h2", "h3", "h4",
      "h5", "h6", "hr", "i", "iframe", "img", "ins",
      "kbd", "li", "mark", "ol", "p", "picture", "pre",
      "q", "s", "samp", "small", "source", "span",
      "strong", "sub", "summary", "sup", "table",
      "tbody", "td", "tfoot", "th", "thead", "tr",
      "u", "ul", "var", "video"
    ]
  },

  "MD034": true,
  "MD035": { "style": "---" },
  "MD036": { "punctuation": ".,;:!?" },
  "MD037": true,
  "MD038": true,
  "MD039": true,
  "MD040": true,
  "MD041": false,
  "MD042": true,
  "MD043": false,
  "MD044": {
    "names": ["markata-go", "GitHub", "GitLab", "JavaScript", "TypeScript"],
    "code_blocks": false
  },
  "MD045": true,
  "MD046": { "style": "fenced" },
  "MD047": true,
  "MD048": { "style": "backtick" },
  "MD049": { "style": "underscore" },
  "MD050": { "style": "asterisk" },
  "MD051": true,
  "MD052": true,
  "MD053": true
}

Rule Categories #

Category	Rules	Description
Headings	MD001-MD003, MD018-MD025	Heading structure and style
Lists	MD004-MD007, MD029-MD032	List formatting
Whitespace	MD009-MD012, MD027-MD028	Spacing and blank lines
Code	MD014, MD031, MD038, MD040, MD046, MD048	Code blocks and inline code
Links	MD034, MD039, MD042, MD051-MD053	Link formatting
Emphasis	MD036-MD037, MD049-MD050	Bold/italic style

Custom markdownlint Rules #

Creating a Custom Rule #

Custom rules are JavaScript modules. Create custom-rules/no-todo-comments.js:

// custom-rules/no-todo-comments.js
module.exports = {
  names: ['no-todo-comments'],
  description: 'Disallow TODO comments in content',
  tags: ['content', 'todo'],
  function: function rule(params, onError) {
    params.tokens.forEach((token) => {
      if (token.type === 'inline') {
        const todoMatch = token.content.match(/\bTODO\b/i);
        if (todoMatch) {
          onError({
            lineNumber: token.lineNumber,
            detail: 'Remove TODO comment before publishing',
            context: token.content,
          });
        }
      }
    });
  },
};

Registering Custom Rules #

In .markdownlint.cjs:

const noTodoComments = require('./custom-rules/no-todo-comments');
const requireDescription = require('./custom-rules/require-description');

module.exports = {
  default: true,
  MD013: false,
  customRules: [noTodoComments, requireDescription],
  'no-todo-comments': true,
  'require-description': { minLength: 50 },
};

Example Custom Rules #

Require minimum content length:

// custom-rules/min-content-length.js
module.exports = {
  names: ['min-content-length'],
  description: 'Enforce minimum content length',
  tags: ['content', 'length'],
  function: function rule(params, onError) {
    const minLength = params.config.minLength || 300;
    const content = params.lines.join('\n');
    
    // Remove frontmatter
    const bodyMatch = content.match(/^---[\s\S]*?---\n([\s\S]*)$/);
    const body = bodyMatch ? bodyMatch[1] : content;
    
    // Remove code blocks and count words
    const textOnly = body.replace(/```[\s\S]*?```/g, '').replace(/`[^`]+`/g, '');
    const wordCount = textOnly.split(/\s+/).filter(Boolean).length;
    
    if (wordCount < minLength) {
      onError({
        lineNumber: 1,
        detail: `Content has ${wordCount} words, minimum is ${minLength}`,
      });
    }
  },
};

Check heading hierarchy:

// custom-rules/heading-hierarchy.js
module.exports = {
  names: ['heading-hierarchy'],
  description: 'Ensure headings follow proper hierarchy',
  tags: ['headings', 'structure'],
  function: function rule(params, onError) {
    let lastLevel = 0;
    
    params.tokens
      .filter((token) => token.type === 'heading_open')
      .forEach((token) => {
        const level = parseInt(token.tag.substring(1), 10);
        
        if (lastLevel > 0 && level > lastLevel + 1) {
          onError({
            lineNumber: token.lineNumber,
            detail: `Heading level jumped from h${lastLevel} to h${level}`,
            context: token.line,
          });
        }
        
        lastLevel = level;
      });
  },
};

Frontmatter Validation Rules #

YAML Schema Validation #

Create a JSON Schema for frontmatter validation. Create frontmatter-schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "markata-go Frontmatter",
  "type": "object",
  "required": ["title", "date", "published"],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "minLength": 50,
      "maxLength": 160
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "published": {
      "type": "boolean"
    },
    "slug": {
      "type": "string",
      "pattern": "^/[a-z0-9-/]+/?$"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9-]+$"
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "author": {
      "type": "string"
    },
    "image": {
      "type": "string",
      "format": "uri-reference"
    },
    "draft": {
      "type": "boolean"
    }
  },
  "additionalProperties": true
}

Validation Script #

Create scripts/validate-frontmatter-schema.sh:

#!/bin/bash
# scripts/validate-frontmatter-schema.sh
# Validates frontmatter against JSON Schema

set -e

# Requires: pip install check-jsonschema pyyaml

schema_file="frontmatter-schema.json"
errors=0

for file in "$@"; do
    [[ "$file" != *.md ]] && continue
    
    # Extract frontmatter
    frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d')
    
    if [ -z "$frontmatter" ]; then
        echo "WARNING: $file - No frontmatter found"
        continue
    fi
    
    # Convert to JSON and validate
    echo "$frontmatter" | python3 -c "
import sys, yaml, json
data = yaml.safe_load(sys.stdin.read())
print(json.dumps(data))
" > /tmp/frontmatter.json
    
    if ! check-jsonschema --schemafile "$schema_file" /tmp/frontmatter.json 2>/dev/null; then
        echo "ERROR: $file - Frontmatter validation failed"
        check-jsonschema --schemafile "$schema_file" /tmp/frontmatter.json 2>&1 | sed 's/^/  /'
        ((errors++))
    fi
done

if [ $errors -gt 0 ]; then
    echo ""
    echo "Found $errors frontmatter validation error(s)"
    exit 1
fi

echo "All frontmatter valid!"

Pre-commit Hook #

repos:
  - repo: local
    hooks:
      - id: validate-frontmatter-schema
        name: Validate Frontmatter Schema
        entry: bash scripts/validate-frontmatter-schema.sh
        language: system
        files: \.(md|markdown)$
        pass_filenames: true
        additional_dependencies:
          - check-jsonschema
          - pyyaml

Project Style Guides #

Documentation Style Guide #

Create a comprehensive style configuration for documentation projects:

{
  "default": true,
  
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD007": { "indent": 2 },
  
  "MD013": false,
  
  "MD022": { "lines_above": 1, "lines_below": 1 },
  "MD024": { "siblings_only": true },
  "MD025": { "front_matter_title": "^\\s*title\\s*[:=]" },
  
  "MD033": {
    "allowed_elements": [
      "details", "summary", "kbd", "br", "sup", "sub",
      "img", "video", "audio", "source", "iframe",
      "table", "thead", "tbody", "tr", "th", "td"
    ]
  },
  
  "MD036": false,
  "MD041": false,
  
  "MD044": {
    "names": [
      "markata-go",
      "GitHub",
      "GitLab",
      "JavaScript",
      "TypeScript",
      "Go",
      "Markdown",
      "YAML",
      "TOML",
      "JSON"
    ],
    "code_blocks": false
  },
  
  "MD046": { "style": "fenced" },
  "MD048": { "style": "backtick" }
}

Blog Style Guide #

For blog-style content with more flexibility:

{
  "default": true,
  
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  
  "MD013": false,
  
  "MD022": { "lines_above": 1, "lines_below": 1 },
  "MD024": { "siblings_only": true },
  
  "MD033": false,
  
  "MD036": false,
  "MD041": false,
  
  "MD046": { "style": "fenced" },
  "MD048": { "style": "backtick" }
}

API Documentation Style #

For technical API documentation:

{
  "default": true,
  
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD007": { "indent": 2 },
  
  "MD013": {
    "line_length": 100,
    "code_blocks": false,
    "tables": false
  },
  
  "MD022": { "lines_above": 1, "lines_below": 1 },
  "MD024": false,
  "MD025": { "front_matter_title": "^\\s*title\\s*[:=]" },
  
  "MD033": {
    "allowed_elements": ["br", "code", "pre"]
  },
  
  "MD036": false,
  "MD041": false,
  
  "MD040": true,
  "MD046": { "style": "fenced" },
  "MD048": { "style": "backtick" }
}

Rule Inheritance and Overrides #

Base Configuration #

Create a base configuration in config/.markdownlint-base.json:

{
  "default": true,
  "MD013": false,
  "MD033": false,
  "MD041": false
}

Extending Base Config #

In project root .markdownlint.json:

{
  "extends": "config/.markdownlint-base.json",
  "MD024": { "siblings_only": true },
  "MD044": {
    "names": ["MyProject"],
    "code_blocks": false
  }
}

Directory-Specific Overrides #

Create override files for specific directories:

docs/.markdownlint.json:

{
  "extends": "../.markdownlint.json",
  "MD013": {
    "line_length": 100
  },
  "MD025": {
    "front_matter_title": "^\\s*title\\s*[:=]"
  }
}

blog/.markdownlint.json:

{
  "extends": "../.markdownlint.json",
  "MD013": false,
  "MD033": false
}

Inline Overrides #

Disable rules for specific sections:

<!-- markdownlint-disable MD033 -->
<details>
<summary>Click to expand</summary>

This content uses raw HTML.

</details>
<!-- markdownlint-enable MD033 -->

Disable rules for entire file:

<!-- markdownlint-disable-file MD013 MD033 -->

# This File Has Custom Rules

Long lines are allowed here...

Creating Custom Validators #

Python Validator #

Create a reusable Python validator:

#!/usr/bin/env python3
# scripts/validate_content.py
"""Content validation for markata-go sites."""

import argparse
import re
import sys
from pathlib import Path
from typing import List, Tuple

import yaml


def extract_frontmatter(content: str) -> Tuple[dict, str]:
    """Extract frontmatter and body from content."""
    match = re.match(r'^---\n(.*?)\n---\n(.*)$', content, re.DOTALL)
    if not match:
        return {}, content
    
    try:
        frontmatter = yaml.safe_load(match.group(1))
        return frontmatter or {}, match.group(2)
    except yaml.YAMLError:
        return {}, content


def check_required_fields(
    frontmatter: dict,
    required: List[str],
    file_path: Path
) -> List[str]:
    """Check for required frontmatter fields."""
    errors = []
    for field in required:
        if field not in frontmatter:
            errors.append(f"{file_path}: Missing required field '{field}'")
    return errors


def check_description_length(
    frontmatter: dict,
    min_length: int,
    max_length: int,
    file_path: Path
) -> List[str]:
    """Check description length for SEO."""
    errors = []
    description = frontmatter.get('description', '')
    
    if description and len(description) < min_length:
        errors.append(
            f"{file_path}: Description too short "
            f"({len(description)} < {min_length})"
        )
    
    if description and len(description) > max_length:
        errors.append(
            f"{file_path}: Description too long "
            f"({len(description)} > {max_length})"
        )
    
    return errors


def check_tags(
    frontmatter: dict,
    allowed_tags: List[str],
    file_path: Path
) -> List[str]:
    """Check that tags are from allowed list."""
    warnings = []
    tags = frontmatter.get('tags', [])
    
    for tag in tags:
        if allowed_tags and tag not in allowed_tags:
            warnings.append(
                f"{file_path}: Unknown tag '{tag}'"
            )
    
    return warnings


def check_images_have_alt(body: str, file_path: Path) -> List[str]:
    """Check that all images have alt text."""
    errors = []
    
    # Find images with empty alt text
    empty_alt = re.findall(r'!\[\s*\]\([^)]+\)', body)
    for img in empty_alt:
        errors.append(f"{file_path}: Image missing alt text: {img[:50]}...")
    
    return errors


def validate_file(
    file_path: Path,
    config: dict
) -> Tuple[List[str], List[str]]:
    """Validate a single file."""
    errors = []
    warnings = []
    
    content = file_path.read_text()
    frontmatter, body = extract_frontmatter(content)
    
    # Required fields
    required = config.get('required_fields', ['title', 'date', 'published'])
    errors.extend(check_required_fields(frontmatter, required, file_path))
    
    # Description length
    desc_min = config.get('description_min_length', 50)
    desc_max = config.get('description_max_length', 160)
    errors.extend(check_description_length(
        frontmatter, desc_min, desc_max, file_path
    ))
    
    # Tags
    allowed_tags = config.get('allowed_tags', [])
    warnings.extend(check_tags(frontmatter, allowed_tags, file_path))
    
    # Images
    if config.get('require_alt_text', True):
        errors.extend(check_images_have_alt(body, file_path))
    
    return errors, warnings


def main():
    parser = argparse.ArgumentParser(description='Validate content files')
    parser.add_argument('files', nargs='+', help='Files to validate')
    parser.add_argument(
        '--config', '-c',
        default='.content-lint.yaml',
        help='Configuration file'
    )
    parser.add_argument(
        '--strict',
        action='store_true',
        help='Treat warnings as errors'
    )
    args = parser.parse_args()
    
    # Load config
    config = {}
    config_path = Path(args.config)
    if config_path.exists():
        config = yaml.safe_load(config_path.read_text())
    
    all_errors = []
    all_warnings = []
    
    for file_arg in args.files:
        file_path = Path(file_arg)
        if not file_path.suffix == '.md':
            continue
        
        errors, warnings = validate_file(file_path, config)
        all_errors.extend(errors)
        all_warnings.extend(warnings)
    
    # Output results
    for error in all_errors:
        print(f"ERROR: {error}")
    
    for warning in all_warnings:
        print(f"WARNING: {warning}")
    
    # Exit code
    if all_errors or (args.strict and all_warnings):
        sys.exit(1)
    
    print(f"Validated {len(args.files)} files successfully")
    sys.exit(0)


if __name__ == '__main__':
    main()

Configuration File #

Create .content-lint.yaml:

# .content-lint.yaml
required_fields:
  - title
  - date
  - published

description_min_length: 50
description_max_length: 160

require_alt_text: true

allowed_tags:
  - documentation
  - tutorial
  - guide
  - reference
  - blog
  - announcement
  - quality-assurance

Pre-commit Integration #

repos:
  - repo: local
    hooks:
      - id: content-validator
        name: Validate Content
        entry: python scripts/validate_content.py
        language: python
        files: \.(md|markdown)$
        pass_filenames: true
        additional_dependencies:
          - pyyaml

Guides Hub

2026-01-24T00:00:00Z

Welcome to the markata-go documentation! Choose a learning path based on your goals, or browse individual guides below.

The Icon Shortcodes guide and Markdown Containers show how to build responsive icon cards, feature rows and architecture diagrams entirely in Markdown. Coding agents can follow the bundled Markata skill for these patterns.

Learning Paths #

Beginner Path #

Time: ~30 minutes | Get your first site running

Perfect if you’re new to markata-go or static site generators in general.

Step	Guide	Time	Description
1	Getting Started	10 min	Installation and first site
2	Quickstart	5 min	Build and serve your site
3	Frontmatter	10 min	Understanding post metadata
4	Markdown Features	5 min	Writing content with Markdown

After completing: You’ll have a working site with your first posts.

Blogger Path #

Time: ~45 minutes | Create a polished blog

For writers and content creators who want a beautiful, functional blog.

Step	Guide	Time	Description
1	Getting Started	10 min	Installation and setup
2	Themes and Styling	10 min	Customize your site’s look
3	Feeds	10 min	RSS, archives, and tag pages
4	Syndication Feeds	5 min	RSS/Atom configuration
5	Deployment	10 min	Go live on GitHub Pages, Netlify, etc.

After completing: You’ll have a deployed blog with RSS feeds and custom styling.

Documentation Site Path #

Time: ~1 hour | Build a documentation site

For teams and projects that need structured documentation.

Step	Guide	Time	Description
1	Getting Started	10 min	Installation and setup
2	Configuration	15 min	Site-wide settings
3	Sidebars	10 min	Navigation sidebars
4	Templates	15 min	Custom layouts
5	Search	10 min	Add site search

After completing: You’ll have a documentation site with navigation, search, and custom templates.

Developer Path #

Time: ~2 hours | Master markata-go

For developers who want full control and customization.

Step	Guide	Time	Description
1	Getting Started	10 min	Installation and setup
2	Configuration	15 min	Complete config reference
3	Templates	20 min	Template system and filters
4	Feeds	15 min	Advanced feed configuration
5	Plugin Development	30 min	Create custom plugins
6	Dynamic Content	15 min	Jinja expressions in content
7	Deployment	15 min	CI/CD and self-hosting

After completing: You’ll understand the full architecture and can extend markata-go for any use case.

All Guides by Topic #

Getting Started #

Getting Started - Complete installation and first site tutorial
Quickstart - 5-minute quick start
Quick Reference - Common commands and snippets

Content Creation #

Frontmatter - Post metadata and custom fields
Markdown Features - Tables, code blocks, admonitions, wikilinks
Image Library - Search and reuse site images
Web Awesome Components - Image comparisons and raw Web Awesome components
Post Formats - HTML, Markdown, and OG card outputs

Configuration #

Configuration - Complete configuration reference
Feeds - Creating filtered, sorted, paginated collections
Syndication Feeds - RSS, Atom, and JSON feed setup

Appearance #

Themes and Styling - Color palettes, CSS variables, custom styles
Templates - Pongo2/Jinja2 template customization
Sidebars - Table of contents and feed navigation

Features #

Search - Pagefind integration for site search
Content Diagnostics - Inspect build dispositions and reason codes
View Transitions - Smooth page navigation animations
Resource Hints - Auto-generate dns-prefetch and preconnect
YouTube Embeds - Embedding YouTube videos
Web Awesome Components - Image comparisons with CDN or vendored assets
Dynamic Content - Jinja expressions in Markdown
Structured Data - JSON-LD and SEO

Deployment #

Deployment - GitHub Pages, Netlify, Vercel, Docker
Self-Hosting - nginx, Caddy, and manual deployment
Nginx-native Redirects - Generate and safely deploy redirects.conf with HTML fallbacks

Advanced #

Agent Skills - Install the bundled markata-go site skill for coding agents
Plugin Development - Creating custom plugins
Static SVG Foundation - Developer-only backend SVG contract and adapter roadmap
Migration - Migrating from other static site generators
Performance and Profiling - Benchmarking and profiling builds
Resource Hints Implementation - Technical details

Quick Links #

Task	Guide
Install markata-go	[Getting Started](/docs/getting-started/#installation)
Change site colors	Themes
Add RSS feed	Syndication Feeds
Fix excessive dns-prefetch	Resource Hints Quick Fix
Deploy to GitHub Pages	Deployment
Configure nginx redirects	Nginx-native Redirects
Create a custom template	Templates
Install the agent skill	Agent Skills
Filter posts by tag	Feeds

Need Help? #

Troubleshooting - Common issues and solutions
Quick Reference - Common commands and config snippets
GitHub Issues - Report bugs or request features

Deploy to Vercel

2026-01-24T00:00:00Z

Vercel provides zero-configuration deployments with excellent performance and edge capabilities. It’s known for its speed and developer experience.

Prerequisites #

A Vercel account (free tier available)
Your markata-go site in a Git repository (GitHub, GitLab, or Bitbucket)

Cost #

Tier	Bandwidth	Builds	Edge Functions	Price
Hobby	100 GB/mo	6,000 min/mo	100,000 exec/mo	$0
Pro	1 TB/mo	Unlimited	1M exec/mo	$20/mo
Enterprise	Custom	Unlimited	Custom	Contact

The Hobby tier is free but limited to personal, non-commercial use.

Method 1: Git Integration (Recommended) #

Step 1: Connect Repository #

Log in to Vercel
Click Add New > Project
Import your Git repository
Authorize Vercel to access your repo

Step 2: Configure Build Settings #

Set these options:

Setting	Value
Framework Preset	Other
Build Command	See below
Output Directory	`public`
Install Command	`echo "No npm dependencies"`

Build Command:

curl -sSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -xzf - && ./go/bin/go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && ~/go/bin/markata-go build --clean

Step 3: Set Environment Variables #

Add these environment variables:

Key	Value
`MARKATA_GO_URL`	`https://your-project.vercel.app`

Step 4: Deploy #

Click Deploy. Vercel will build and deploy your site.

Method 2: vercel.json Configuration #

Create vercel.json in your repository root for more control:

{
  "buildCommand": "curl -sSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -xzf - && ./go/bin/go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && ~/go/bin/markata-go build --clean",
  "outputDirectory": "public",
  "installCommand": "echo 'No npm dependencies'",
  "framework": null,
  "headers": [
    {
      "source": "/static/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*).html",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=0, must-revalidate"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    }
  ],
  "redirects": [
    {
      "source": "/old-path/:path*",
      "destination": "/new-path/:path*",
      "permanent": true
    }
  ]
}

Method 3: CLI Deployment #

Deploy manually using the Vercel CLI:

# Install CLI
npm install -g vercel

# Login
vercel login

# Build your site locally
markata-go build --clean

# Deploy preview (from public directory)
cd public && vercel

# Deploy to production
cd public && vercel --prod

Custom Domain Setup #

Step 1: Add Domain #

Go to your project’s Settings > Domains
Enter your domain (e.g., example.com)
Click Add

Step 2: Configure DNS #

Vercel provides DNS records to add at your registrar:

For apex domain:

Type: A
Name: @
Value: 76.76.21.21

For www subdomain:

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Step 3: Verify and Enable HTTPS #

Vercel automatically provisions SSL certificates once DNS is configured. This usually takes a few minutes.

Step 4: Update Configuration #

Update your markata-go.toml:

[markata-go]
url = "https://example.com"

Set the production environment variable:

vercel env add MARKATA_GO_URL production
# Enter: https://example.com

Environment Variables #

Manage environment variables per environment:

# Add to production
vercel env add MARKATA_GO_URL production
# Value: https://example.com

# Add to preview (for PR deployments)
vercel env add MARKATA_GO_URL preview
# Value: (leave empty to use Vercel's preview URL)

# Add to development
vercel env add MARKATA_GO_URL development
# Value: http://localhost:8080

# List all variables
vercel env ls

# Pull variables to local .env
vercel env pull

Preview Deployments #

Vercel automatically creates preview deployments for every push:

Production: your-project.vercel.app
Preview: your-project-git-branch-username.vercel.app
PR Preview: Automatically commented on GitHub PRs

Edge Functions #

Add edge functions for dynamic functionality:

// api/hello.js
export const config = {
  runtime: 'edge',
};

export default function handler(request) {
  return new Response(JSON.stringify({ message: 'Hello from the Edge!' }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Access at /api/hello.

Analytics #

Enable Vercel Analytics for performance insights:

Go to Project Settings > Analytics
Click Enable

Add the analytics script to your template:

<script defer src="/_vercel/insights/script.js"></script>

Speed Insights #

Enable Speed Insights for Core Web Vitals:

Go to Project Settings > Speed Insights
Click Enable

Troubleshooting #

Build Fails: Go Installation Issues #

The build command needs to install Go first. Ensure your build command is correct:

{
  "buildCommand": "curl -sSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -xzf - && ./go/bin/go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && ~/go/bin/markata-go build --clean"
}

Build Timeout #

Hobby tier has a 45-second build limit. Consider:

Upgrading to Pro for longer builds

Pre-building locally and deploying the output:

markata-go build --clean
cd public && vercel --prod

404 on Page Refresh #

Vercel handles clean URLs automatically for static sites. Ensure your output directory is correct.

Environment Variables Not Applied #

Check that variables are set for the correct environment:

vercel env ls

Production, Preview, and Development are separate environments.

Assets Not Loading #

Verify your MARKATA_GO_URL matches your deployment URL:

# Check current value
vercel env ls | grep MARKATA_GO_URL

Performance Optimization #

Enable Compression #

Vercel automatically compresses responses with gzip and Brotli.

Configure Caching #

In vercel.json:

{
  "headers": [
    {
      "source": "/static/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*).xml",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
}

Use Edge Network #

Vercel’s edge network automatically serves your site from the nearest location to each visitor.

Monorepo Support #

For monorepos, configure the root directory:

{
  "installCommand": "echo 'Skip install'",
  "buildCommand": "cd packages/my-site && curl -sSL ... && markata-go build",
  "outputDirectory": "packages/my-site/public"
}

Or set the Root Directory in project settings.

Next Steps #

Vercel Docs - Official documentation
Configuration Guide - Customize your markata-go site
Themes Guide - Change your site’s appearance

Deploy to Netlify

2026-01-24T00:00:00Z

Netlify offers continuous deployment, serverless functions, form handling, and a powerful CDN. It’s excellent for teams and sites that need more than just static hosting.

Prerequisites #

A Netlify account (free tier available)
Your markata-go site in a Git repository (GitHub, GitLab, or Bitbucket)

Cost #

Tier	Bandwidth	Build Minutes	Forms	Price
Free	100 GB/mo	300 min/mo	100/mo	$0
Pro	1 TB/mo	25,000 min/mo	Unlimited	$19/mo
Business	1 TB/mo	25,000 min/mo	Unlimited	$99/mo

The free tier is generous enough for most personal and small business sites.

Method 1: Git Integration (Recommended) #

Step 1: Connect Repository #

Log in to Netlify
Click Add new site > Import an existing project
Choose your Git provider and authorize Netlify
Select your repository

Step 2: Configure Build Settings #

Enter these settings:

Setting	Value
Base directory	(leave empty)
Build command	`go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && markata-go build --clean`
Publish directory	`public`

Step 3: Set Environment Variables #

Click Advanced and add:

Key	Value
`GO_VERSION`	`1.22`
`MARKATA_GO_URL`	`https://your-site.netlify.app`

Step 4: Deploy #

Click Deploy site. Netlify will build and deploy your site automatically.

Method 2: netlify.toml Configuration #

For more control, create netlify.toml in your repository root:

[build]
  command = "go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && markata-go build --clean"
  publish = "public"

[build.environment]
  GO_VERSION = "1.22"
  MARKATA_GO_URL = "https://your-site.netlify.app"

# Production context
[context.production]
  environment = { MARKATA_GO_URL = "https://example.com" }

# Deploy previews (automatic for PRs)
[context.deploy-preview]
  command = "go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && markata-go build"

# Branch deploys
[context.branch-deploy]
  command = "go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && markata-go build"

# Security and caching headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

[[headers]]
  for = "/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

# Redirects
[[redirects]]
  from = "/old-path/*"
  to = "/new-path/:splat"
  status = 301

Method 3: CLI Deployment #

Deploy manually using the Netlify CLI:

# Install CLI
npm install -g netlify-cli

# Login
netlify login

# Initialize project (first time)
netlify init

# Build your site
markata-go build --clean

# Deploy preview
netlify deploy --dir=public

# Deploy to production
netlify deploy --dir=public --prod

Custom Domain Setup #

Step 1: Add Domain in Netlify #

Go to Site settings > Domain management
Click Add custom domain
Enter your domain (e.g., example.com)

Step 2: Configure DNS #

Option A: Use Netlify DNS (Recommended)

Click Set up Netlify DNS for your domain

Update your domain registrar’s nameservers to Netlify’s:

dns1.p01.nsone.net
dns2.p01.nsone.net
dns3.p01.nsone.net
dns4.p01.nsone.net

Option B: External DNS

Add these records at your DNS provider:

For apex domain:

Type: A
Name: @
Value: 75.2.60.5

For www subdomain:

Type: CNAME
Name: www
Value: your-site.netlify.app

Step 3: Enable HTTPS #

Netlify automatically provisions Let’s Encrypt certificates. Go to Domain management > HTTPS and click Verify DNS configuration.

Step 4: Update Configuration #

Update your markata-go.toml:

[markata-go]
url = "https://example.com"

And your netlify.toml:

[context.production.environment]
  MARKATA_GO_URL = "https://example.com"

Deploy Previews #

Netlify automatically creates preview deployments for pull requests. Each PR gets a unique URL like:

https://deploy-preview-123--your-site.netlify.app

To customize preview behavior, add to netlify.toml:

[context.deploy-preview]
  command = "go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && markata-go build"
  
[context.deploy-preview.environment]
  # Leave MARKATA_GO_URL empty to use Netlify's preview URL

Forms (No Backend Required) #

Netlify can handle form submissions without a backend:

<form name="contact" method="POST" data-netlify="true">
  <input type="hidden" name="form-name" value="contact" />
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

Form submissions appear in Site settings > Forms.

Serverless Functions #

Add serverless functions in netlify/functions/:

// netlify/functions/hello.js
exports.handler = async (event, context) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello from Netlify Functions!" })
  };
};

Access at /.netlify/functions/hello.

Troubleshooting #

Build Fails: Go Not Found #

Ensure GO_VERSION is set in environment variables:

[build.environment]
  GO_VERSION = "1.22"

Build Timeout #

Free tier has a 15-minute build limit. Optimize your build:

[build]
  command = """
    if [ ! -f $HOME/go/bin/markata-go ]; then
      go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
    fi
    markata-go build --clean
  """

Assets Not Loading #

Check your site URL configuration:

# View current config
netlify env:list

# Set production URL
netlify env:set MARKATA_GO_URL https://example.com

Deploy Preview URL Issues #

For deploy previews, let Netlify handle the URL:

[context.deploy-preview.environment]
  # Don't set MARKATA_GO_URL - let Netlify use the preview URL

Custom Headers Not Applied #

Ensure netlify.toml is in your repository root (not in a subdirectory).

Performance Optimization #

Enable Asset Optimization #

In Site settings > Build & deploy > Post processing:

Enable Pretty URLs
Enable Asset optimization (minify CSS/JS)
Enable Prerendering

Configure Caching #

[[headers]]
  for = "/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*.xml"
  [headers.values]
    Cache-Control = "public, max-age=3600"

Next Steps #

Netlify Docs - Official documentation
Configuration Guide - Customize your markata-go site
Feeds Guide - Set up RSS and Atom feeds

Deployment Guide

2026-01-24T00:00:00Z

markata-go generates static sites that can be deployed anywhere that serves HTML files. This guide helps you choose the best platform for your needs.

Platform Comparison #

Platform	Free Tier	Custom Domain	Build Time	Best For
GitHub Pages	Unlimited	Yes (HTTPS)	~2 min	Open source projects
Netlify	100 GB/mo	Yes (HTTPS)	~1 min	Teams, forms, functions
Vercel	100 GB/mo	Yes (HTTPS)	~1 min	Performance, edge
Cloudflare Pages	Unlimited	Yes (HTTPS)	~2 min	Global CDN, Workers
AWS S3	5 GB (12 mo)	Yes (via CF)	Manual	Enterprise, AWS stack
Docker	N/A	Self-managed	~30 sec	Self-hosted, control
Kubernetes Helm	N/A	Yes	Cluster-dependent	Homelabs, ArgoCD, in-cluster builds

Quick Decision Guide #

Choose GitHub Pages if:

Your code is on GitHub
You want zero configuration
You don’t need server-side features

Choose Netlify if:

You need forms, functions, or split testing
You want automatic deploy previews
You’re working with a team

Choose Vercel if:

Performance is your top priority
You want edge functions
You need analytics

Choose Cloudflare Pages if:

You want unlimited bandwidth
You need Workers integration
Global performance matters

Choose AWS S3 if:

You’re already in the AWS ecosystem
You need fine-grained access control
Enterprise compliance is required

Choose Docker if:

You want full control
You’re self-hosting other services
You need offline capabilities

Choose Kubernetes Helm if:

You already deploy with ArgoCD or Helm
You want in-cluster builds from a source archive
You want same-origin /api/search served with the site

Building for Production #

Before deploying to any platform, build your site:

# Standard production build
markata-go build --clean

# Build with custom URL
MARKATA_GO_URL=https://example.com markata-go build --clean

# Verbose build for debugging
markata-go build --clean -v

Output Structure #

After building, your public/ directory contains:

public/
├── index.html              # Home page
├── blog/
│   ├── index.html          # Blog listing
│   ├── rss.xml             # RSS feed
│   └── atom.xml            # Atom feed
├── posts/
│   └── my-post/
│       └── index.html      # Individual post
├── static/                 # Assets (CSS, JS, images)
└── sitemap.xml

Environment Variables #

All platforms support these environment variables:

Variable	Purpose	Example
`MARKATA_GO_URL`	Base URL for links and feeds	`https://example.com`
`MARKATA_GO_OUTPUT`	Output directory	`public`

Next Steps #

Choose a platform guide to get started:

GitHub Pages - Free hosting for GitHub repos
Netlify - Feature-rich with generous free tier
Vercel - Performance-focused deployment
Cloudflare Pages - Unlimited bandwidth
AWS S3 - Enterprise-grade static hosting
Docker - Self-hosted containers

For Kubernetes and source-archive deployments, see the chart README under helm-chart/README.md in the markata-go repository.

For self-hosting on your own servers, see the Self-Hosting Guide.

Deploy to GitHub Pages

2026-01-24T00:00:00Z

GitHub Pages provides free hosting for static sites directly from a GitHub repository. It’s the easiest way to deploy if your code is already on GitHub.

Prerequisites #

A GitHub account
Your markata-go site in a GitHub repository
Git installed locally

Cost #

Tier	Storage	Bandwidth	Custom Domain
Free	1 GB	100 GB/mo	Yes (HTTPS)

GitHub Pages is completely free for public repositories. Private repositories require GitHub Pro ($4/mo) or a paid organization plan.

Method 1: GitHub Actions (Recommended) #

This method automatically builds and deploys your site on every push to main.

Step 1: Create the Workflow #

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Install markata-go
        run: go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest

      - name: Build site
        run: markata-go build --clean
        env:
          MARKATA_GO_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 2: Configure Repository Settings #

Go to your repository on GitHub
Navigate to Settings > Pages
Under Source, select GitHub Actions
Push your changes to trigger the workflow

Step 3: Access Your Site #

After the workflow completes, your site will be available at:

https://<username>.github.io/<repository-name>/

Method 2: Manual Deployment #

For more control or if you can’t use GitHub Actions.

Step 1: Build Locally #

# Set the URL for your GitHub Pages site
export MARKATA_GO_URL=https://username.github.io/repo-name

# Build the site
markata-go build --clean

Step 2: Deploy to gh-pages Branch #

# Navigate to output directory
cd public

# Initialize git and push to gh-pages branch
git init
git add -A
git commit -m "Deploy site"
git push -f git@github.com:username/repo-name.git main:gh-pages

Or use the gh-pages npm package:

npm install -g gh-pages
markata-go build --clean
gh-pages -d public

Step 3: Configure Repository #

Go to Settings > Pages
Under Source, select Deploy from a branch
Select the gh-pages branch and / (root) folder
Click Save

Custom Domain Setup #

Step 1: Add CNAME File #

Create static/CNAME (no extension) with your domain:

example.com

This file will be copied to public/CNAME during build.

Step 2: Update Configuration #

In your markata-go.toml:

[markata-go]
url = "https://example.com"

Step 3: Configure DNS #

For apex domain (example.com):

Add these A records pointing to GitHub’s servers:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

For subdomain (www.example.com or blog.example.com):

Add a CNAME record:

Type: CNAME
Name: www (or blog)
Value: username.github.io

Step 4: Enable HTTPS #

Go to Settings > Pages
Under Custom domain, enter your domain
Check Enforce HTTPS (may take up to 24 hours)

Troubleshooting #

Build Fails: “command not found: markata-go” #

Ensure Go is set up correctly in your workflow:

- name: Setup Go
  uses: actions/setup-go@v5
  with:
    go-version: '1.22'
    cache: true

- name: Install markata-go
  run: |
    go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
    echo "$(go env GOPATH)/bin" >> $GITHUB_PATH

404 Errors on Subpages #

Make sure your site URL matches the GitHub Pages URL:

# For project sites (username.github.io/repo-name)
MARKATA_GO_URL=https://username.github.io/repo-name markata-go build

# For user sites (username.github.io)
MARKATA_GO_URL=https://username.github.io markata-go build

CSS/JS Not Loading #

Check that asset paths are relative or use the correct base URL. The workflow above sets MARKATA_GO_URL automatically.

Custom Domain Not Working #

Verify DNS propagation: dig example.com
Ensure CNAME file exists in output
Wait up to 24 hours for HTTPS certificate

Workflow Not Triggering #

Ensure the workflow file is in the correct location:

.github/workflows/deploy.yml

And that you’re pushing to the main branch (or adjust the workflow trigger).

Advanced Configuration #

Caching for Faster Builds #

Add caching for the markata-go binary:

- name: Cache markata-go
  uses: actions/cache@v4
  with:
    path: ~/go/bin/markata-go
    key: markata-go-${{ runner.os }}-v1

- name: Install markata-go
  run: |
    if [ ! -f ~/go/bin/markata-go ]; then
      go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
    fi

Preview Deployments for Pull Requests #

Deploy preview versions for PRs:

name: Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Build
        run: |
          go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
          markata-go build --clean
        env:
          MARKATA_GO_URL: https://username.github.io/repo/pr-${{ github.event.number }}

      - name: Deploy Preview
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          destination_dir: pr-${{ github.event.number }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Preview: https://username.github.io/repo/pr-${{ github.event.number }}/'
            })

Next Steps #

Custom Domain Setup - GitHub’s official docs
Configuration Guide - Customize your markata-go site
Themes Guide - Change your site’s appearance

Deploy with Docker

2026-01-24T00:00:00Z

Docker provides a consistent, reproducible environment for building and serving your markata-go site. It’s ideal for self-hosting, local development, and integration with container orchestration platforms.

Prerequisites #

Docker installed (Get Docker)
Docker Compose (optional, for multi-container setups)
Your markata-go site ready to build

Official markata-go Images #

markata-go publishes two official container images for different workflows:

ghcr.io/waylonwalker/markata-go:<version>: Minimal runtime image (scratch) that runs the markata-go binary directly.
ghcr.io/waylonwalker/markata-go-builder:<version>: Builder image with /bin/sh, aws, openssl, core utilities, rsync, image encoders (avifenc, cwebp), Pagefind (standalone binary), Tailwind CLI (standalone binary), bundled CDN asset cache, bundled Mermaid JS, and Chromium for mermaid rendering (via Go-native chromedp, no Node.js required).

Builder Image Quick Start #

docker run --rm \
  -v "$PWD":/site \
  -w /site \
  ghcr.io/waylonwalker/markata-go-builder:latest \
  sh -c 'markata-go build --clean'

Builder Image Publish Script #

docker run --rm \
  -v "$PWD":/site \
  -v /webroot:/webroot \
  -w /site \
  ghcr.io/waylonwalker/markata-go-builder:latest \
  sh -c 'set -eu; ts=$(date -u +%Y%m%d%H%M%S); markata-go build --clean; rsync -a --delete public/ /webroot/releases/$ts/; ln -sfn releases/$ts /webroot/current'

Chromium Mermaid Rendering in Containers #

If your site uses mode = "chromium" for pre-rendered Mermaid diagrams, set no_sandbox = true in your config. The Chromium sandbox requires kernel capabilities that Docker restricts by default:

[markata-go.mermaid]
mode = "chromium"

[markata-go.mermaid.chromium]
no_sandbox = true

The builder image includes Chromium. For custom images, see Chromium in Containers in the configuration guide for installation options including the lightweight chrome-headless-shell binary that requires no root access.

Cost #

Setup	Cost	Best For
Local Docker	Free	Development, testing
Self-hosted server	$5-20/mo (VPS)	Personal sites, full control
Container platforms	Varies	Production, scaling

Method 1: Simple Nginx Container #

The simplest approach: build locally and serve with nginx.

Step 1: Build Your Site #

markata-go build --clean

Step 2: Create Dockerfile #

Create Dockerfile in your project root:

FROM nginx:alpine

# Copy built site to nginx
COPY public/ /usr/share/nginx/html/

# Custom nginx config for clean URLs
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Step 3: Create nginx Configuration #

Create nginx.conf:

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # Enable gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;

    # MIME types for txt/md files
    location ~ \.(txt|md)$ {
        default_type text/plain;
        charset utf-8;
    }

    # Try exact file first (for /robots.txt), then index.html, then directory
    # This supports reversed redirects where canonical files are at /slug.txt
    location / {
        try_files $uri $uri/index.html $uri/ =404;
    }

    # Cache static assets
    location /static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Don't cache HTML
    location ~* \.html$ {
        expires -1;
        add_header Cache-Control "no-store, no-cache, must-revalidate";
    }

    # Security headers
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
}

Step 4: Build and Run #

# Build the image
docker build -t my-site .

# Run the container
docker run -d -p 8080:80 --name my-site my-site

# View your site at http://localhost:8080

Method 2: Multi-Stage Build #

Build the site inside Docker for fully reproducible builds.

Dockerfile with Multi-Stage Build #

# Stage 1: Build the site
FROM golang:1.22-alpine AS builder

# Install git (needed for go install)
RUN apk add --no-cache git

# Install markata-go
RUN go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest

# Set working directory
WORKDIR /site

# Copy site source
COPY . .

# Build the site
ENV MARKATA_GO_URL=https://example.com
RUN markata-go build --clean

# Stage 2: Serve with nginx
FROM nginx:alpine

# Copy built site from builder stage
COPY --from=builder /site/public/ /usr/share/nginx/html/

# Custom nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Build and Run #

# Build with your production URL
docker build \
  --build-arg MARKATA_GO_URL=https://example.com \
  -t my-site .

# Run
docker run -d -p 8080:80 --name my-site my-site

Method 3: Docker Compose #

For development with live reload or multi-service setups.

docker-compose.yml #

version: '3.8'

services:
  site:
    build: .
    ports:
      - "8080:80"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Optional: Add Watchtower for automatic updates
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 3600 site

Commands #

# Start services
docker compose up -d

# View logs
docker compose logs -f site

# Rebuild after changes
docker compose build && docker compose up -d

# Stop services
docker compose down

Method 4: Development with Live Reload #

For local development with automatic rebuilds.

docker-compose.dev.yml #

version: '3.8'

services:
  dev:
    image: golang:1.22-alpine
    working_dir: /site
    volumes:
      - .:/site
      - go-cache:/go
    ports:
      - "8080:8080"
    command: |
      sh -c '
        apk add --no-cache git
        go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
        markata-go serve
      '
    environment:
      - MARKATA_GO_URL=http://localhost:8080

volumes:
  go-cache:

Run Development Server #

docker compose -f docker-compose.dev.yml up

Production Deployment #

Deploying to a VPS #

Build and Push to Registry

# Build image
docker build -t your-registry/my-site:latest .

# Push to registry (Docker Hub, GitHub Container Registry, etc.)
docker push your-registry/my-site:latest

Pull and Run on Server

# On your server
docker pull your-registry/my-site:latest
docker run -d \
  --name my-site \
  -p 80:80 \
  --restart unless-stopped \
  your-registry/my-site:latest

With HTTPS (Traefik) #

Use Traefik as a reverse proxy with automatic HTTPS.

docker-compose.prod.yml #

version: '3.8'

services:
  traefik:
    image: traefik:v2.10
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=you@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt
    restart: unless-stopped

  site:
    build: .
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.site.rule=Host(`example.com`)"
      - "traefik.http.routers.site.entrypoints=websecure"
      - "traefik.http.routers.site.tls.certresolver=letsencrypt"
      - "traefik.http.routers.site-http.rule=Host(`example.com`)"
      - "traefik.http.routers.site-http.entrypoints=web"
      - "traefik.http.routers.site-http.middlewares=redirect-to-https"
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
    restart: unless-stopped

volumes:
  letsencrypt:

With HTTPS (Caddy) #

Caddy provides automatic HTTPS with simpler configuration.

Caddyfile #

example.com {
    root * /srv
    file_server
    encode gzip

    # MIME types for txt/md files
    @txtmd path *.txt *.md
    header @txtmd Content-Type "text/plain; charset=utf-8"

    header /static/* Cache-Control "public, max-age=31536000, immutable"
    header *.html Cache-Control "no-cache, must-revalidate"

    # Try exact file first (for /robots.txt), then index.html, then directory
    try_files {path} {path}/index.html {path}/
}

docker-compose.caddy.yml #

version: '3.8'

services:
  caddy:
    image: caddy:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./public:/srv
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:

CI/CD Integration #

GitHub Actions #

name: Build and Deploy Docker

on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
          build-args: |
            MARKATA_GO_URL=https://example.com

  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            docker stop my-site || true
            docker rm my-site || true
            docker run -d \
              --name my-site \
              -p 80:80 \
              --restart unless-stopped \
              ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

Container Orchestration #

Kubernetes Deployment #

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: markata-site
spec:
  replicas: 2
  selector:
    matchLabels:
      app: markata-site
  template:
    metadata:
      labels:
        app: markata-site
    spec:
      containers:
        - name: site
          image: your-registry/my-site:latest
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: "128Mi"
              cpu: "100m"
          livenessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: markata-site
spec:
  selector:
    app: markata-site
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: markata-site
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts:
        - example.com
      secretName: markata-site-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: markata-site
                port:
                  number: 80

Troubleshooting #

Container Won’t Start #

Check logs:

docker logs my-site

Common issues:

Port already in use: Change the host port (-p 8081:80)
Permission denied: Check file permissions in copied directories

404 Errors on Subpages #

Ensure nginx is configured for the reversed redirect structure:

# MIME types for txt/md files
location ~ \.(txt|md)$ {
    default_type text/plain;
    charset utf-8;
}

# Try exact file first, then index.html, then directory
location / {
    try_files $uri $uri/index.html $uri/ =404;
}

This order ensures:

/robots.txt serves the canonical file directly
/my-post/ serves /my-post/index.html
Directory requests fall back correctly

Large Image Size #

Optimize your Dockerfile:

# Use alpine-based images
FROM nginx:alpine

# Use .dockerignore to exclude unnecessary files

Create .dockerignore:

.git
node_modules
*.md
Dockerfile
docker-compose*.yml

Build Fails in Multi-Stage #

Ensure Go modules are available:

# If using go modules
COPY go.mod go.sum ./
RUN go mod download

CSS/JS Not Loading #

Verify MARKATA_GO_URL matches your deployment:

docker build --build-arg MARKATA_GO_URL=https://example.com -t my-site .

Performance Optimization #

Enable Brotli Compression #

# In nginx.conf
brotli on;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;

Requires nginx with brotli module:

FROM fholzer/nginx-brotli:latest

Resource Limits #

# In docker-compose.yml
services:
  site:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 128M
        reservations:
          cpus: '0.1'
          memory: 64M

Health Checks #

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD wget -q --spider http://localhost/ || exit 1

Security Best Practices #

Run as Non-Root User #

FROM nginx:alpine

# Create non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

# Copy files
COPY --chown=appuser:appgroup public/ /usr/share/nginx/html/

# Switch to non-root user (for processes that don't need root)
# Note: nginx master process needs root for port 80

Read-Only Filesystem #

services:
  site:
    read_only: true
    tmpfs:
      - /var/cache/nginx
      - /var/run

Security Scanning #

# Scan image for vulnerabilities
docker scout cve my-site:latest

# Or use Trivy
trivy image my-site:latest

Next Steps #

Self-Hosting Guide - More self-hosting options
Configuration Guide - Customize your markata-go site
Themes Guide - Change your site’s appearance

Deploy to Cloudflare Pages

2026-01-24T00:00:00Z

Cloudflare Pages provides fast global CDN deployment with unlimited bandwidth and Workers integration. It’s an excellent choice for high-traffic sites.

Prerequisites #

A Cloudflare account (free tier available)
Your markata-go site in a Git repository (GitHub or GitLab)

Cost #

Tier	Bandwidth	Builds	Sites	Price
Free	Unlimited	500/mo	Unlimited	$0
Pro	Unlimited	5,000/mo	Unlimited	$20/mo
Business	Unlimited	20,000/mo	Unlimited	$200/mo

The free tier offers unlimited bandwidth, making it ideal for high-traffic sites.

Method 1: Git Integration (Recommended) #

Step 1: Connect Repository #

Log in to the Cloudflare Dashboard
Go to Workers & Pages > Create application > Pages
Click Connect to Git
Select your Git provider and repository

Step 2: Configure Build Settings #

Setting	Value
Framework preset	None
Build command	See below
Build output directory	`public`
Root directory	(leave empty)

Build Command:

curl -sSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -xzf - && ./go/bin/go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && ~/go/bin/markata-go build --clean

Step 3: Set Environment Variables #

Click Environment variables and add:

Variable	Value
`MARKATA_GO_URL`	`https://your-project.pages.dev`

Set this for both Production and Preview environments.

Step 4: Deploy #

Click Save and Deploy. Cloudflare will build and deploy your site.

Method 2: Wrangler CLI #

Deploy using the Wrangler CLI for more control:

# Install wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Build your site locally
MARKATA_GO_URL=https://example.com markata-go build --clean

# Create a new Pages project (first time)
wrangler pages project create my-site

# Deploy
wrangler pages deploy public --project-name=my-site

For subsequent deployments:

markata-go build --clean
wrangler pages deploy public --project-name=my-site

Custom Domain Setup #

Step 1: Add Domain to Cloudflare #

If your domain isn’t already on Cloudflare:

Go to Websites > Add a Site
Enter your domain
Update nameservers at your registrar to Cloudflare’s

Step 2: Connect Domain to Pages #

Go to your Pages project
Click Custom domains > Set up a custom domain
Enter your domain (e.g., example.com)
Click Activate domain

Cloudflare automatically configures DNS and provisions SSL certificates.

Step 3: Add www Subdomain (Optional) #

Add www.example.com as another custom domain
Or create a redirect rule in Rules > Redirect Rules:
- If hostname equals www.example.com
- Then redirect to https://example.com

Step 4: Update Configuration #

Update your markata-go.toml:

[markata-go]
url = "https://example.com"

Headers and Redirects #

Using _headers File #

Create static/_headers (copied to output during build):

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()

/static/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate

/*.xml
  Cache-Control: public, max-age=3600

Using _redirects File #

Create static/_redirects:

# Redirect old URLs
/old-path/* /new-path/:splat 301
/blog/old-post /blog/new-post 301

# Proxy API requests
/api/* https://api.example.com/:splat 200

Preview Deployments #

Cloudflare Pages automatically creates preview deployments for:

Every branch push
Every pull request

Preview URLs follow this pattern:

<commit-hash>.<project-name>.pages.dev

You can also access branch-specific previews:

<branch-name>.<project-name>.pages.dev

Workers Integration #

Adding a Worker #

Create functions/ directory for Pages Functions (Workers):

// functions/api/hello.js
export async function onRequest(context) {
  return new Response(JSON.stringify({
    message: "Hello from Cloudflare Workers!"
  }), {
    headers: { "Content-Type": "application/json" }
  });
}

Access at /api/hello.

Adding Middleware #

Create functions/_middleware.js for all routes:

export async function onRequest(context) {
  // Add security headers
  const response = await context.next();
  response.headers.set("X-Custom-Header", "value");
  return response;
}

Environment Variables #

Setting Variables #

In the Cloudflare dashboard:

Go to your Pages project
Click Settings > Environment variables
Add variables for Production and Preview separately

Variable	Production	Preview
`MARKATA_GO_URL`	`https://example.com`	(empty)

Accessing in Workers #

// functions/api/config.js
export async function onRequest(context) {
  const url = context.env.MARKATA_GO_URL;
  return new Response(JSON.stringify({ url }));
}

Troubleshooting #

Build Fails: Go Not Found #

The build environment doesn’t have Go pre-installed. Use the build command that installs Go:

curl -sSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -xzf - && ./go/bin/go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest && ~/go/bin/markata-go build --clean

Build Timeout #

Free tier builds timeout after 20 minutes. Optimize by:

Caching Go installation (not currently supported)

Pre-building locally and deploying:

markata-go build --clean
wrangler pages deploy public

404 on Subpages #

Ensure your _redirects file doesn’t interfere. Cloudflare Pages serves index.html files automatically for clean URLs.

Headers Not Applied #

Verify _headers file is in your output directory:

markata-go build --clean
cat public/_headers

Custom Domain Not Working #

Ensure domain is added to Cloudflare (not just Pages)
Check DNS is proxied (orange cloud enabled)
Wait for SSL certificate provisioning

Performance Features #

Automatic Optimizations #

Cloudflare Pages automatically provides:

Global CDN distribution
Brotli compression
HTTP/2 and HTTP/3
Early Hints
Smart caching

Web Analytics #

Enable Cloudflare Web Analytics (free):

Go to Analytics in your Cloudflare dashboard
Click Web Analytics > Add a site
Add the script to your template:

<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "your-token"}'></script>

Page Rules #

Create Page Rules for advanced caching:

Go to Rules > Page Rules
Create rules for your domain

Example: Cache everything for static assets:

example.com/static/*
Cache Level: Cache Everything
Edge Cache TTL: 1 month

Comparison with Cloudflare Workers Sites #

Feature	Pages	Workers Sites
Git integration	Yes	No
Preview deploys	Automatic	Manual
Build system	Built-in	External
Functions	Pages Functions	Workers
Best for	Static sites	Dynamic apps

Pages is recommended for markata-go sites.

Next Steps #

Cloudflare Pages Docs - Official documentation
Configuration Guide - Customize your markata-go site
Feeds Guide - Set up RSS and Atom feeds

Deploy to AWS S3

2026-01-24T00:00:00Z

Amazon S3 provides highly durable object storage that’s ideal for hosting static websites. Combined with CloudFront CDN, it offers enterprise-grade performance and security.

Prerequisites #

An AWS account
AWS CLI installed and configured
Your markata-go site ready to build

Cost #

Service	Free Tier	After Free Tier
S3 Storage	5 GB (12 months)	~$0.023/GB/month
S3 Requests	20,000 GET (12 months)	~$0.0004/1000 requests
CloudFront	1 TB transfer (12 months)	~$0.085/GB
Route 53	N/A	$0.50/hosted zone/month

A typical blog costs $1-5/month after the free tier expires.

Architecture Options #

Setup	Complexity	HTTPS	Custom Domain	CDN
S3 only	Low	No	Limited	No
S3 + CloudFront	Medium	Yes	Yes	Yes
S3 + CloudFront + Route 53	High	Yes	Yes (apex)	Yes

This guide covers the recommended S3 + CloudFront setup.

Step 1: Create S3 Bucket #

Using AWS Console #

Go to S3 Console
Click Create bucket
Enter bucket name (e.g., my-site-bucket)
Choose a region close to your audience
Uncheck Block all public access (we’ll use CloudFront for access)
Click Create bucket

Using AWS CLI #

# Create bucket
aws s3 mb s3://my-site-bucket --region us-east-1

# Enable static website hosting
aws s3 website s3://my-site-bucket --index-document index.html --error-document 404.html

Step 2: Configure Bucket Policy #

Create a bucket policy to allow CloudFront access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-site-bucket/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
        }
      }
    }
  ]
}

You’ll update this policy after creating the CloudFront distribution.

Step 3: Create CloudFront Distribution #

Using AWS Console #

Go to CloudFront Console
Click Create distribution
Configure origin:
- Origin domain: Select your S3 bucket
- Origin access: Origin access control settings (recommended)
- Click Create control setting > Create
Configure default cache behavior:
- Viewer protocol policy: Redirect HTTP to HTTPS
- Allowed HTTP methods: GET, HEAD
- Cache policy: CachingOptimized
Configure settings:
- Price class: Use all edge locations (or choose based on audience)
- Default root object: index.html
Click Create distribution

Update S3 Bucket Policy #

After creating the distribution, update the bucket policy with the correct ARN:

# Get distribution ARN from CloudFront console
# Update bucket policy with the distribution ARN

Step 4: Build and Deploy #

Build Your Site #

# Set the CloudFront URL (or custom domain)
export MARKATA_GO_URL=https://d1234abcd.cloudfront.net

# Build
markata-go build --clean

Deploy to S3 #

# Sync all files
aws s3 sync public/ s3://my-site-bucket --delete

# With cache headers for static assets
aws s3 sync public/static/ s3://my-site-bucket/static/ \
  --cache-control "public, max-age=31536000, immutable"

# HTML files with no-cache
aws s3 sync public/ s3://my-site-bucket \
  --exclude "static/*" \
  --cache-control "public, max-age=0, must-revalidate"

Invalidate CloudFront Cache #

After deploying, invalidate the cache to see changes immediately:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

Step 5: Custom Domain Setup #

Option A: Using Route 53 (Recommended) #

Create Hosted Zone

aws route53 create-hosted-zone --name example.com --caller-reference $(date +%s)

Update Domain Nameservers

Get the nameservers from Route 53 and update them at your registrar.

Request SSL Certificate

In AWS Certificate Manager (ACM) - must be in us-east-1 for CloudFront:

aws acm request-certificate \
  --domain-name example.com \
  --subject-alternative-names "*.example.com" \
  --validation-method DNS \
  --region us-east-1

Add Certificate to CloudFront

Update your distribution:
- Alternate domain names: example.com, www.example.com
- Custom SSL certificate: Select your ACM certificate
Create DNS Records

In Route 53, create A records as aliases to your CloudFront distribution.

Option B: External DNS #

Request ACM certificate (as above)
Validate via DNS by adding CNAME records at your registrar
Add alternate domain names to CloudFront
Create CNAME record pointing to your CloudFront domain:
```
www.example.com -> d1234abcd.cloudfront.net
```

Note: Apex domains (example.com without www) require Route 53 or a DNS provider that supports ALIAS/ANAME records.

Automation with GitHub Actions #

Create .github/workflows/deploy.yml:

name: Deploy to AWS

on:
  push:
    branches: [main]

env:
  AWS_REGION: us-east-1
  S3_BUCKET: my-site-bucket
  CLOUDFRONT_DISTRIBUTION_ID: E1234567890ABC

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::ACCOUNT_ID:role/GitHubActionsRole
          aws-region: ${{ env.AWS_REGION }}

      - name: Build
        run: |
          go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest
          markata-go build --clean
        env:
          MARKATA_GO_URL: https://example.com

      - name: Deploy to S3
        run: |
          # Static assets with long cache
          aws s3 sync public/static/ s3://${{ env.S3_BUCKET }}/static/ \
            --cache-control "public, max-age=31536000, immutable"
          
          # Everything else
          aws s3 sync public/ s3://${{ env.S3_BUCKET }} \
            --exclude "static/*" \
            --cache-control "public, max-age=0, must-revalidate" \
            --delete

      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ env.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"

IAM Role for GitHub Actions #

Create an IAM role with OIDC trust for GitHub:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:*"
        }
      }
    }
  ]
}

Attach a policy allowing S3 and CloudFront access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::my-site-bucket",
        "arn:aws:s3:::my-site-bucket/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
    }
  ]
}

Troubleshooting #

Access Denied Errors #

Check bucket policy allows CloudFront access
Verify Origin Access Control is configured
Ensure the distribution ARN in bucket policy is correct

404 on Subpages #

Configure CloudFront error pages:

Go to your distribution > Error pages
Create custom error response:
- HTTP error code: 403
- Response page path: /index.html
- HTTP response code: 200

Or use a CloudFront Function for clean URLs (see below).

CloudFront Function for Clean URLs #

Create a function to handle clean URLs:

function handler(event) {
  var request = event.request;
  var uri = request.uri;
  
  // Check whether the URI is missing a file extension
  if (!uri.includes('.')) {
    // If URI doesn't end with /, add it
    if (!uri.endsWith('/')) {
      uri += '/';
    }
    // Append index.html
    request.uri = uri + 'index.html';
  }
  
  return request;
}

Attach to your distribution’s viewer request.

Changes Not Appearing #

Wait for CloudFront cache to expire, or

Create a cache invalidation:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

SSL Certificate Issues #

ACM certificate must be in us-east-1 region
Certificate must be validated (check ACM console)
Alternate domain names must match certificate

Cost Optimization #

Reduce CloudFront Costs #

Use Price Class 100 (North America and Europe only) for regional sites
Enable Compress objects automatically
Set appropriate cache TTLs

Reduce S3 Costs #

Enable S3 Intelligent-Tiering for rarely accessed sites
Use S3 Standard for frequently accessed content
Clean up old versions if versioning is enabled

Monitor Costs #

Set up AWS Budgets to alert you:

aws budgets create-budget \
  --account-id YOUR_ACCOUNT_ID \
  --budget file://budget.json \
  --notifications-with-subscribers file://notifications.json

Next Steps #

AWS S3 Docs - Official S3 documentation
CloudFront Docs - CDN configuration
Configuration Guide - Customize your markata-go site