selfdoc Documentation

Architecture

2026-09-15T00:00:00Z

This page explains how selfdoc works at a high level -- what happens when you run `selfdoc build`, how directives get resolved, and how themes control the output. For internal implementation details (tokenizer internals, extractor protocol, resolver dispatch chain), see [Internals](../internals/).

Blog Posts

2026-09-15T00:00:00Z

selfdoc includes a blog system for publishing chronological content alongside your documentation. Blog posts are Markdown files with a TOML frontmatter block, stored in a dedicated directory within your project. Posts are unversioned -- they exist outside the multi-version docs system -- and are published to the unified documentation assembly alongside your API reference and guides.

Check Guide

2026-09-15T00:00:00Z

`selfdoc check` is your documentation linter. It validates every directive in your templates, measures how much of your public API is documented, runs SEO best-practice checks, and detects stale descriptions. Run it locally before pushing, or wire it into CI for automated enforcement.

selfdoc assembly

2026-09-15T00:00:00Z

selfdoc baseline

2026-09-15T00:00:00Z

selfdoc blog

2026-09-15T00:00:00Z

selfdoc build

2026-09-15T00:00:00Z

selfdoc check

2026-09-15T00:00:00Z

selfdoc deploy

2026-09-15T00:00:00Z

selfdoc gen-data

2026-09-15T00:00:00Z

selfdoc gen

2026-09-15T00:00:00Z

selfdoc CLI Reference

2026-09-15T00:00:00Z

selfdoc init

2026-09-15T00:00:00Z

selfdoc layout

2026-09-15T00:00:00Z

selfdoc quality

2026-09-15T00:00:00Z

selfdoc serve

2026-09-15T00:00:00Z

selfdoc spell-corpus

2026-09-15T00:00:00Z

Code Blocks

2026-09-15T00:00:00Z

Fenced code blocks in selfdoc get automatic syntax highlighting, language labels, and a copy button. Beyond the basics, you can enable line numbers, interactive run buttons, inline annotations, diff highlighting, and automatic language tabs.

Comparisons

2026-09-15T00:00:00Z

selfdoc takes a different angle from most documentation generators: it extracts content directly from source code through a catalogue of built-in directives, reads nine languages in a single tool, and produces a complete static site with search, SEO, and theming -- out of one Go binary with no runtime to install beside it.

Configuration

2026-09-15T00:00:00Z

selfdoc is configured via a `selfdoc.json` file in your project root. Run `selfdoc init` to generate a starter config interactively, or create one manually.

Custom Directives

2026-09-15T00:00:00Z

selfdoc's built-in directives cover common patterns like module references and schema tables, but sometimes you need something project-specific. Custom directives let you write a script that generates Markdown content at build time, driven by your own logic.

Deployment

2026-09-15T00:00:00Z

selfdoc generates a fully static site that can be deployed anywhere. Two providers have built-in support with `selfdoc deploy`: **Cloudflare Pages** and **GitHub Pages**.

Directives Guide

2026-09-15T00:00:00Z

Directives are selfdoc's mechanism for embedding live, code-extracted content in Markdown templates. Instead of manually copying API signatures, config schemas, or CLI help text into your documentation, you place a directive marker in your template. At build time, selfdoc resolves each directive by reading your source code, config files, or project metadata, and replaces the marker with generated Markdown content. The result: documentation that stays in sync with the implementation automatically.

Directives Reference

2026-09-15T00:00:00Z

selfdoc directives are inline blocks in Markdown templates that get resolved into content at build time. They pull live information from your source code, so documentation stays in sync with the implementation.

Editor Guide

2026-09-15T00:00:00Z

`selfdoc blog editor serve` runs a local authoring app for blog posts. It opens in a browser, lists the repositories a hand-written registry declares, shows each one's posts, and puts the post source in an editor beside a live preview.

Atom Feeds

2026-09-15T00:00:00Z

Every selfdoc site gets a `feed.xml` in the build output. It is a standard Atom 1.0 feed that RSS readers, news aggregators, and automation tools can subscribe to. No setup required -- it happens automatically during `selfdoc build`.

Frontmatter

2026-09-15T00:00:00Z

Every page under `.stricttools/docs/` and every post under the posts directory opens with a frontmatter block: TOML between `+++` fences.

Data Generation

2026-09-15T00:00:00Z

selfdoc can run scripts at build time to generate data files that your documentation pages reference. Scripts run inside a bubblewrap (bwrap) sandbox for isolation -- they get read-only access to specific directories and can only write to the output directory.

API Reference

2026-09-15T00:00:00Z

Getting Started

2026-09-15T00:00:00Z

This guide walks you through installing selfdoc, setting up a project, writing your first directive, and previewing your documentation site locally.

Glossary Guide

2026-09-15T00:00:00Z

selfdoc can build a glossary from terms defined across your documentation. Define a term once, and selfdoc auto-links the first mention on every other page back to its definition. You also get a generated glossary page that aggregates all terms alphabetically.

Glossary

2026-09-15T00:00:00Z

This page defines the key terms used throughout the selfdoc documentation.

internal/address

2026-09-15T00:00:00Z

internal/blog/assembly

2026-09-15T00:00:00Z

internal/blog/chrome

2026-09-15T00:00:00Z

internal/blog/editor/assets

2026-09-15T00:00:00Z

internal/blog/editor/registry

2026-09-15T00:00:00Z

internal/blog/editor

2026-09-15T00:00:00Z

internal/blog/listing

2026-09-15T00:00:00Z

internal/blog/posts

2026-09-15T00:00:00Z

internal/blog/preview

2026-09-15T00:00:00Z

internal/blog/serving

2026-09-15T00:00:00Z

internal/blog/shared

2026-09-15T00:00:00Z

internal/blog/site

2026-09-15T00:00:00Z

internal/blog/sitedirectives

2026-09-15T00:00:00Z

internal/blog/unified

2026-09-15T00:00:00Z

internal/blog/unifiedcheck

2026-09-15T00:00:00Z

internal/blog/verify

2026-09-15T00:00:00Z

internal/catalog

2026-09-15T00:00:00Z

internal/check

2026-09-15T00:00:00Z

internal/cli

2026-09-15T00:00:00Z

internal/config

2026-09-15T00:00:00Z

internal/content

2026-09-15T00:00:00Z

internal/cv

2026-09-15T00:00:00Z

internal/deploy

2026-09-15T00:00:00Z

internal/directives

2026-09-15T00:00:00Z

internal/docs

2026-09-15T00:00:00Z

internal/effects

2026-09-15T00:00:00Z

internal/excludes

2026-09-15T00:00:00Z

internal/extractors/dart

2026-09-15T00:00:00Z

internal/extractors/golang

2026-09-15T00:00:00Z

internal/extractors/kotlin

2026-09-15T00:00:00Z

internal/extractors/python

2026-09-15T00:00:00Z

internal/extractors/sql

2026-09-15T00:00:00Z

internal/extractors/svelte

2026-09-15T00:00:00Z

internal/extractors/swift

2026-09-15T00:00:00Z

internal/extractors/typescript

2026-09-15T00:00:00Z

internal/extractors/zig

2026-09-15T00:00:00Z

internal/extractors

2026-09-15T00:00:00Z

internal/fleet

2026-09-15T00:00:00Z

internal/gen

2026-09-15T00:00:00Z

internal/gendata

2026-09-15T00:00:00Z

internal/gitcommit

2026-09-15T00:00:00Z

internal/html

2026-09-15T00:00:00Z

internal/icons

2026-09-15T00:00:00Z

internal/identity

2026-09-15T00:00:00Z

internal/js

2026-09-15T00:00:00Z

internal/layout

2026-09-15T00:00:00Z

internal/lints

2026-09-15T00:00:00Z

internal/manifest

2026-09-15T00:00:00Z

internal/ownership

2026-09-15T00:00:00Z

internal/page

2026-09-15T00:00:00Z

internal/payloadschemas

2026-09-15T00:00:00Z

internal/prose

2026-09-15T00:00:00Z

internal/quality

2026-09-15T00:00:00Z

internal/render

2026-09-15T00:00:00Z

internal/resolution

2026-09-15T00:00:00Z

internal/resolver

2026-09-15T00:00:00Z

internal/revisions

2026-09-15T00:00:00Z

internal/robots

2026-09-15T00:00:00Z

internal/spellcorpus

2026-09-15T00:00:00Z

internal/spelling

2026-09-15T00:00:00Z

internal/staleness

2026-09-15T00:00:00Z

internal/strictclisupport

2026-09-15T00:00:00Z

internal/tables

2026-09-15T00:00:00Z

internal/themes

2026-09-15T00:00:00Z

internal/tokenizer

2026-09-15T00:00:00Z

internal/urls

2026-09-15T00:00:00Z

internal/util

2026-09-15T00:00:00Z

Internals

2026-09-15T00:00:00Z

This page documents selfdoc's internal design for contributors and anyone extending or debugging the system. For the user-facing overview, see [Architecture](../architecture/).

The .stricttools/ layout

2026-09-15T00:00:00Z

Every directory selfdoc owns in a repository lives under one hidden directory at the repository root, `.stricttools/`, and every directory under it is named for its FUNCTION rather than for the tool that writes it. Another tool's state sits beside selfdoc's, under its own function name, in the same directory.

llms.txt

2026-09-15T00:00:00Z

selfdoc automatically generates 2 files that make your documentation accessible to AI assistants and large language models. No configuration needed -- they appear in your build output alongside `sitemap.xml` and `robots.txt`.

Multi-Language Support

2026-09-15T00:00:00Z

selfdoc ships an extractor for each of the languages in the table below. Each one knows how to read its source files and resolve directives against them. The same directive syntax works across all of them -- only the source file format changes.

Quality Guide

2026-09-15T00:00:00Z

`selfdoc quality` measures how mature your project's documentation setup is. It produces two independent scores: a **tier** (0--5) that tracks which selfdoc features you have adopted, and a **content grade** (A--F) that measures how much documentation you have relative to your source code.

rlsbl Integration

2026-09-15T00:00:00Z

selfdoc and rlsbl have a bidirectional relationship. selfdoc is aware of rlsbl's commit tooling and changelog conventions, while rlsbl can run selfdoc checks during release and trigger builds and deploys post-release. If both tools are present in a project, they cooperate automatically.

Root Files

2026-09-15T00:00:00Z

selfdoc can generate root-level project files (like `README.md` and `CLAUDE.md`) from templates that live in your `.stricttools/docs/` directory. The templates use the same directive syntax as your documentation pages, so the generated files always reflect the current state of your source code.

Search

2026-09-15T00:00:00Z

Every selfdoc site ships with full-text search out of the box. No external services, no API keys, no CDN: the build runs [Pagefind](https://pagefind.app/) over the pages it just wrote, and Pagefind emits both the index and the search UI into `pagefind/` at the output root. Users search from any page via the keyboard shortcut or the UI widget.

selfdoc

2026-09-15T00:00:00Z

SEO

2026-09-15T00:00:00Z

selfdoc generates a full suite of SEO artifacts automatically during every build. You get meta tags, structured data, sitemaps, social cards, and AI discoverability files without writing any HTML or config beyond what you already have.

Staleness Detection

2026-09-15T00:00:00Z

You update a page's content but forget to update the frontmatter `description`. Now your meta tags, OG cards, and search snippets show outdated text. selfdoc catches this automatically by tracking content hashes.

Theming

2026-09-15T00:00:00Z

selfdoc ships with three built-in themes and a comprehensive set of CSS custom properties that you can override without touching theme internals. Dark mode, high contrast, and print stylesheets work out of the box.

selfdoc vs the Competition: Documentation Generators Compared

2026-06-29T00:00:00Z

The documentation generator landscape shifted in 2026. Material for MkDocs entered maintenance mode after years of dominance, and its successor Zensical launched with a Rust-powered build engine. Meanwhile, the JavaScript ecosystem continues to fragment across React, Vue, and Astro-based options. This post compares selfdoc against six major tools across the features that matter most for technical documentation.