https://smmh.dev/selfdoc/ 2026-08-12T00:00:00Z Code-aware static site generator that resolves directive blocks in Markdown templates into live content extracted from source code. https://smmh.dev/selfdoc/architecture/ 2026-08-12T00: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/).

https://smmh.dev/selfdoc/blog-guide/ 2026-08-12T00:00:00Z

selfdoc includes a blog system for publishing chronological content alongside your documentation. Blog posts are Markdown files with YAML frontmatter, 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.

https://smmh.dev/selfdoc/check-guide/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/cli-baseline/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-build/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-check/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-deploy/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-gen-data/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-gen/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-index/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-init/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-quality/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-serve/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/cli-spell-corpus/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen (strictcli), do not edit -->

https://smmh.dev/selfdoc/code-blocks/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/comparisons/ 2026-08-12T00:00:00Z

selfdoc takes a different angle from most documentation generators: it extracts content directly from source code via 21 built-in directive types, supports 3 languages in a single tool, and produces a complete static site with search, SEO, and theming -- all from pure Python with 2 direct runtime dependencies and nothing to compile.

https://smmh.dev/selfdoc/configuration/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/custom-directives/ 2026-08-12T00:00:00Z

selfdoc's 21 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 Python script that generates Markdown content at build time, driven by your own logic.

https://smmh.dev/selfdoc/directives-guide/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/feeds/ 2026-08-12T00: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`.

https://smmh.dev/selfdoc/gen-data-guide/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/gen-index/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/getting-started/ 2026-08-12T00:00:00Z

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

https://smmh.dev/selfdoc/glossary-guide/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/glossary-terms/ 2026-08-12T00:00:00Z

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

https://smmh.dev/selfdoc/internals/ 2026-08-12T00: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/).

https://smmh.dev/selfdoc/llms-txt/ 2026-08-12T00: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`.

https://smmh.dev/selfdoc/multi-language/ 2026-08-12T00:00:00Z

selfdoc supports 3 languages out of the box: **Python**, **Go**, and **TypeScript/JavaScript**. Each language has its own extractor that knows how to read source files and resolve directives. The same directive syntax works across all languages -- only the source file format changes.

https://smmh.dev/selfdoc/rlsbl-integration/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/root-files/ 2026-08-12T00:00:00Z

selfdoc can generate root-level project files (like `README.md` and `CLAUDE.md`) from templates that live in your `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.

https://smmh.dev/selfdoc/search/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/selfdoc-__main__/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-_version/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-deploy/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-docs/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-dart/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-go/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-kotlin/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-python/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-sql/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-svelte/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-swift/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-typescript/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors-zig/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-extractors/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-gen/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-gendata/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-icons/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-js-loader/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-js/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-manifest/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-ownership/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-quality/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-resolver/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-spell_corpus/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-strictcli_support/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-tables/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-tokenizer/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-urls/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc-utils/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/selfdoc/ 2026-08-12T00:00:00Z

<!-- generated by selfdoc gen, do not edit -->

https://smmh.dev/selfdoc/seo/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/staleness/ 2026-08-12T00: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.

https://smmh.dev/selfdoc/quality-guide/ 2026-07-29T00: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.

https://smmh.dev/selfdoc/selfdoc-build/ 2026-07-29T00:00:00Z

The build module is the central pipeline that turns Markdown templates and source code into a complete documentation site. It loads `selfdoc.json`, scans the `docs/` directory for templates, resolves all directives against the project's source files, converts the resolved Markdown to HTML via `selfdoc.html`, and writes the output to disk. A single invocation handles multi-version builds (checking out tagged versions from git), multi-locale builds (iterating locale directories), and the generation of auxiliary files such as sitemaps, Atom feeds, OpenGraph images, `robots.txt`, `llms.txt`, and search indexes.

https://smmh.dev/selfdoc/selfdoc-check/ 2026-07-29T00:00:00Z

The check module validates documentation quality across multiple dimensions. Its main entry point, `check_docs()`, scans every Markdown template in `docs/`, parses directives, and attempts to resolve each one against the project's source code -- reporting per-directive OK/FAILED status. It then computes coverage: what fraction of public symbols in the source are referenced by at least one directive. Beyond directives, the module runs a suite of SEO lint rules (heading structure, title length, missing descriptions, alt text quality, link targets, color contrast) and detects stale or drifted descriptions via content hashing against stored baselines.

https://smmh.dev/selfdoc/selfdoc-cli/ 2026-07-29T00:00:00Z

The cli module defines selfdoc's command-line interface using strictcli. It registers the top-level `selfdoc` app and all subcommands: `init`, `build`, `serve`, `check`, `gen`, `gen-data`, `deploy`, and `quality`, plus command groups for `post`, `assembly`, and `baseline`. Each command function parses flags, loads config via `selfdoc.config`, and delegates to the corresponding implementation module. The `serve` command starts an HTTP server with live-reload for local development.

https://smmh.dev/selfdoc/selfdoc-config/ 2026-07-29T00:00:00Z

The config module loads and validates `selfdoc.json`, the project-level configuration file that controls every aspect of the documentation build. It defines a declarative schema (`CONFIG_SCHEMA`) of `FieldSpec` entries covering required fields like `source` (list of source paths with languages) and `base_url`, plus dozens of optional settings for theming, search engine selection, code block behavior, SEO metadata, deploy provider, versioning, localization, and more. The `load_config()` function reads the JSON file, rejects unknown keys, validates each field against its spec (type, pattern, choices, min/max constraints), applies defaults, and runs post-validation checks.

https://smmh.dev/selfdoc/selfdoc-directives/ 2026-07-29T00:00:00Z

The directives module parses selfdoc's structured marker syntax, which embeds source-code extraction commands inside Markdown templates. It recognizes six marker types: `:-:` (one-liner/self-closing), `:<:` (block open), `:@:` (block attribute), `:=:` (body separator), `:::` (body content line), and `:>:` (block close). The parser is a line-oriented state machine that tracks fenced code blocks to avoid interpreting markers inside code examples. Each parsed directive becomes a `Directive` dataclass carrying its name, key-value attributes, optional body lines, and source location.

https://smmh.dev/selfdoc/selfdoc-html/ 2026-07-29T00:00:00Z

The html module is selfdoc's built-in Markdown-to-HTML converter with zero required runtime dependencies. It handles headings (with auto-generated slug anchors and table-of-contents extraction), fenced code blocks (with optional Pygments syntax highlighting, language icons, line numbers, annotations, and run buttons), tables, ordered and unordered lists, definition lists, blockquotes, GitHub-flavored admonitions, inline formatting (bold, italic, strikethrough, code, links, images), and cross-page glossary term linking. The converter also supports higher-level structural patterns like code tabs, step guides, API entry wrapping, and diff-highlighted code blocks.

https://smmh.dev/selfdoc/monorepo-conversion/ 2026-07-06T00:00:00Z

This document describes the conversion of selfdoc from a standalone rlsbl-managed repo to a monorepo with three releasables: `selfdoc_core`, `selfdoc`, and `selfblog`.

https://smmh.dev/blog/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.

https://smmh.dev/selfdoc/deployment/ 2026-06-29T00: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**.

https://smmh.dev/selfdoc/directives/ 2026-06-29T00: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.

https://smmh.dev/selfdoc/theming/ 2026-06-29T00:00:00Z

selfdoc ships with two 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.