selfdoc v0.15.1 /Changelog
On this page

#Changelog

#0.15.1

Fix pipe escaping in unclosed backtick spans.

#Fixes

  • Bug fix. Pipes inside unclosed backtick spans in table cells are now correctly escaped.

#0.15.0

#Features

  • New utility. render_markdown_table in selfdoc.tables -- public API for rendering markdown tables with alignment support, pretty-print mode, and backtick-aware pipe escaping.
  • Init command. Detects all languages in multi-language projects for config generation.

#0.14.1

#Fixes

  • Fix. Python test files (test_*.py, conftest.py) and test directories (tests/, test/, __tests__/) are now excluded from documentation coverage, matching what selfdoc gen already excluded.

#0.14.0

#Breaking

  • Breaking. Removed javascript alias from the extractor registry. Use typescript for both TypeScript and JavaScript files.

#Features

  • New feature. Unsupported languages in source entries get a stub extractor instead of a config error. Supported languages work normally alongside unsupported ones. LANG001 lint error reports which source paths lack an extractor.

#Fixes

  • Fix. Source walks now skip .venv, node_modules, __pycache__, and other non-source directories. Previously, a .venv/ inside a source path would generate hundreds of doc pages for third-party packages.

#0.13.1

#Fixes

  • Fix. Go root packages in multi-source-path projects no longer crash with ambiguity errors. Each source path's root package gets a unique qualified path instead of the ambiguous path=".".

#0.13.0

#Breaking

  • Breaking. Top-level language config field removed. Each source entry is now an object with path and language fields: {"path": "src/", "language": "python"}.

#Features

  • New feature. Zig language extractor with support for pub fn, pub const, pub var, struct/enum/union declarations, /// doc comments, //! module docs, and test block extraction.
  • New feature. Resolver dispatches directives to the correct language extractor based on source path. Cross-language path ambiguity is detected and errors.
  • New feature. selfdoc gen and selfdoc check work across multiple languages in a single project. Coverage enforcement applies to all languages -- undocumented symbols in any language cause failure.
  • New feature. list-modules directive auto-detects language from source path. project.language variable returns comma-separated list for multi-language projects.

#0.12.0

#Breaking

  • 100% coverage enforced. selfdoc check now requires all public symbols to be documented on non-skeleton pages. The min_coverage config field is removed.

#Features

  • Extractor accuracy. Python extractor respects __all__ for public symbol detection. Go extractor handles exported symbols inside const() and var() blocks.
  • Stale file tracking. selfdoc gen now tracks and commits deleted stale doc files alongside newly generated ones.
  • Schema provenance. selfdoc gen and selfdoc check validate that .strictcli/schema.json belongs to the current project via a project_id field.

#Fixes

  • Hash consistency. selfdoc gen updates content hashes after generating, eliminating the 'run check twice' ritual. Gen, check, and build now use consistent locale-prefixed hash keys.
  • Skeleton-only display. selfdoc check now shows which symbols are only referenced on skeleton pages when documented coverage is below 100%.
  • Wider lint suppression. lint_ignore config now accepts all lint code formats (e.g., STALE001, VER002), not just SEO codes.
  • Safer stale cleanup. Stale generated files are now deleted after new files are written, preventing data loss if generation fails midway.
  • Git command safety. All git subprocess calls use -- separator before filenames, preventing filenames from being mistaken for git options.

#0.11.0

#Features

  • New feature. Config-driven redirects for renamed/deleted doc pages. Add a redirects list in selfdoc.json with {from, to} page slugs — the build expands across all locale/version combos, generating both Cloudflare _redirects rules and HTML meta-refresh pages. Existing pages in cached old versions are preserved.
  • Docs. Added prose documentation for the exclude attribute on table-schema and table-config directives.

#0.10.0

#Features

  • New feature. exclude attribute for table-schema and table-config directives, allowing users to exclude specific top-level keys when rendering JSON/TOML/JSONC config files as tables.

#Fixes

  • Bug fix. Go extractor table-schema now correctly renders JSON/TOML config files instead of failing with 'no struct types found' when the file exists in the project.

#0.9.1

#Fixes

  • Fix. Go gen root package now correctly uses ref path="." instead of the module name.

#0.9.0

#Features

  • New feature. Consolidated version detection with new VER002/VER003 lint codes that error when selfdoc.json version drifts from the project manifest.
  • New feature. table-endpoint content directive renders REST API documentation from OpenAPI 3.x JSON specs.
  • New feature. Two-tier coverage reporting distinguishes truly documented symbols (on human-written pages) from merely referenced symbols (on auto-generated skeleton pages).
  • New feature. selfdoc.json now supports an optional version field for explicit project version declaration.

#Fixes

  • Fix. Go gen now produces per-package (per-directory) documentation pages instead of broken per-file pages.

#0.8.1

#Features

  • Check validates all versions. selfdoc check now extracts and validates old tagged versions, not just the working tree. Monorepo version pinning lets docs-site releases freeze constituent project versions.
  • gen_data dogfooding. selfdoc's own docs now use a gen_data script that extracts the directive catalog from source code.

#Fixes

  • Fix frontmatter list parsing. Use bracket syntax [a, b, c] for list values instead of comma detection, which broke description fields containing commas.

#0.8.0

#Breaking

  • Breaking: always-prefixed URLs. All output now uses /<locale>/<version>/page/ URL structure. versions and locales arrays are now required in selfdoc.json. Version and locale picker dropdowns in the header.

#Features

  • Internal refactoring. Introduced BuildContext/PageContext/SearchEntry dataclasses, extracted JS to real files, decomposed \_wrap\_page into sub-renderers, extracted build\_single from build().
  • Multi-version docs. Build documentation for multiple tagged versions from git history. Version picker, old-version banner, per-version SEO (noindex, canonical to latest), git tag extraction with caching. --version CLI flag for dev builds.
  • Localization support. Parallel locale directories (docs/en/, docs/fa/), multi-locale build loop, hreflang tags, per-locale sitemaps with sitemap-index, backward compat for single-locale projects. --locale CLI flag.
  • Search filters. Filter search by version, locale, group, type, target, project, and tags. Syntax: key=value, key=a|b (OR), -key=value (NOT). Auto-injected version=latest default. Chip UI for active filters.
  • Monorepo unified site. New selfdoc/unified.py module builds one site from multiple projects. Hybrid sidebar with project groups, auto-generated landing page, rlsbl workspace.toml validation, unified search/sitemap/glossary, check_unified for all constituent projects.
  • Documentation overhaul. Rewrote homepage, restructured nav into 4 groups, enriched 20 API reference stubs, populated 23-term glossary, added callouts, created 14 new guide pages (search, SEO, code blocks, custom directives, check, comparisons, rlsbl integration, feeds, llms.txt, glossary guide, multi-language, root files, gen-data, staleness).

#Fixes

  • Fix Python logo SVG. The two snake halves in code block language icons no longer appear separated.

#0.7.0

#Breaking

  • strictcli dependency bumped to >=0.7.0 for --dump-schema support.

#Features

  • Shared resolution pipeline. Directive resolution centralized in a single pass, eliminating redundant walks and double resolution in selfdoc check.
  • **--dry-run flag for selfdoc check.** Reports staleness without writing hashes or committing. Hash computation centralized in staleness.py.
  • Glossary opt-out. Set "glossary": false in selfdoc.json to suppress auto-generated glossary page. Feed entry limit. Set "feed_max_entries": N to limit the Atom feed to the N most recent pages.
  • Schema.json-based CLI extraction. Replaced AST-based CLI structure extraction with reading .strictcli/schema.json. Richer data (flag choices, hidden flags, deprecated commands). Go projects get CLI documentation for the first time.

#0.6.0

#Features

  • Declarative config schema. Config validation is now driven by a schema (FieldType enum + FieldSpec dataclass) instead of procedural code. Unknown top-level keys in selfdoc.json are now rejected.
  • Five new directives. list-modules, table-commands, table-directives, table-config-schema, and var for generating module lists, CLI command tables, directive catalogs, config reference tables, and project metadata interpolation.
  • Root file generation. selfdoc gen can now produce root-level Markdown files (CLAUDE.md, README.md, etc.) from underscore-prefixed templates in docs/. Configure via root_files in selfdoc.json. Generated files are read-only (0o444) with an auto-generated header.

#Fixes

  • Underscore-prefixed templates excluded from lint. selfdoc check now skips _*.md files in docs/, matching the existing build exclusion.

#0.5.2

#Fixes

  • CLI page preservation fix end-to-end. Handwritten CLI page descriptions now actually survive selfdoc gen (the 0.5.1 preservation logic was defeated by stale-file cleanup deleting CLI pages before they could be read for preservation).

#0.5.1

#Features

  • Module page descriptions from docstrings. selfdoc gen now seeds new module pages with the first line of the module's docstring instead of the generic 'API reference for X' template; quote-wrapping length is also fixed.

#Fixes

  • CLI page description preservation. Handwritten description frontmatter on CLI pages (per-command, per-group, and the CLI index) now survives selfdoc gen runs, matching the behavior added for module pages in 0.5.0.
  • Sticky column visuals. Sticky first column in tables now preserves row stripe and hover backgrounds instead of showing a flat fill.

#0.5.0

#Breaking

  • API entry cards default to off. Re-enable via auto_detect.api_entries in config.

#Features

  • Module page descriptions preserved across regenerations. selfdoc gen now reads each existing page's frontmatter; if the description: has been customized (i.e., differs from the default 'API reference for X' template), it's preserved instead of overwritten. Bootstrap workflow: run selfdoc gen once, then handwrite each page's description in its frontmatter — subsequent selfdoc gen runs keep your descriptions.
  • Table redesign. Tables now use content-based widths and support sortable columns.
  • Language icons for code blocks. New display modes: colorful, monochrome, or none.
  • Optional line numbers for code blocks.
  • Subtle code block buttons with a coherent visual design.
  • Configurable run button, page navigation, and page progress indicators.
  • Theme-consistent styling for mark, kbd, abbr, del, ins, small, figure, var, samp, cite.
  • New directives: prose-desc, list-tree, table-dep, list-features.
  • CLI page descriptions use command help text instead of generic boilerplate.

#Fixes

  • Demo knob panel cleanup: removed unused knobs, added font options, fixed bugs.
  • Visual fixes: heading anchor hover, collapsible padding, code background, sidebar spacing.
  • Favicon and OG card now use the theme accent color.
  • Improved coverage matching for generated doc pages.
  • Recursive coverage matching now uses startswith for prefix-based directory matches.
  • code-help directive: path resolution and strictcli flag extraction for Go projects.

#0.4.5

#Breaking

  • Removed deprecated --warn-only flag (warnings are non-fatal by default since 0.4.0)

#Features

  • JSON schema for selfdoc check --format json output (schemas/check-output.schema.json)

#0.4.4

#Fixes

  • Build now cleans the output directory before writing, preventing stale files from previous builds

#0.4.3

#Features

  • Directive catalog now includes descriptions, attribute specs, and usage examples for all core directives
  • Generated API and CLI reference pages now appear in organized sidebar groups

#0.4.2

#Features

  • Auto-commit prefers rlsbl commit when available, marking commits with Autogenerated trailer for changelog coverage exemption

#0.4.1

  • No user-facing changes.

#0.4.0

#Features

  • Directive syntax redesigned: new attribute-based format (:-:, :<:, :>:) with a formal directive catalog replacing the old :::name arg syntax. All existing directive blocks must be migrated. The glossary directive is now list-glossary.
  • Custom directive scripts must update from resolve(arg, config) to resolve(attrs, config, body). Body content is now forwarded.
  • Extractors refactored to a LanguageExtractor protocol with a registry. Custom extractor integrations may need updating.
  • URL scheme changed from flat (guide.html) to directory-index (guide/index.html, served as guide/). All canonical URLs, sitemap entries, and internal links updated. External links pointing to old .html URLs will 404.
  • H1 headings are now auto-generated from the page title. The first # heading in Markdown is consumed as the title source (not rendered as-is). Multiple # headings in a single page now cause a build error.
  • selfdoc build no longer exits 1 for lint warnings. Exit 1 is reserved for errors only. The --warn-only flag is deprecated (warnings are non-fatal by default).
  • selfdoc gen command: auto-generates documentation pages from source code structure, with exclusion patterns, generated: true frontmatter, and stale file cleanup
  • selfdoc gen-data command: runs sandboxed scripts (via bubblewrap) to generate CSV/JSON data files for documentation
  • First-class strictcli support: auto-detects strictcli usage and generates CLI documentation pages
  • Description staleness detection: selfdoc check warns (STALE001) when a page description no longer matches page content, tracked via content hashing in .selfdoc/hashes/
  • Pluggable search engine: choose "builtin", "fuse", or "minisearch" via the search_engine config field
  • Landing page template: hero section with tagline, CTA button, and feature cards, configured via branding config field
  • Cross-page term linking: <dfn> definitions automatically linked across pages with dotted-underline .term-link styling
  • Documentation coverage for Go (exported symbols) and TypeScript/JavaScript (export declarations), previously Python-only
  • Per-symbol coverage tracking with configurable min_coverage threshold
  • Callout directives (note, tip, warning, danger, important) as first-class directive types
  • Feed filtering via feed: false frontmatter; changelog pages auto-detected and excluded by default
  • Reading progress bar fixed below the topbar
  • Scroll affordance gradients on overflowing code blocks and tables
  • Sticky first column on horizontally-scrolling tables
  • auto_detect config field to disable step guide and API entry heuristics globally or per-page via auto_steps/auto_api frontmatter
  • Markdown block tokenizer (selfdoc/tokenizer.py): standalone module with zero dependencies, 10 token types. Used internally for both HTML rendering and lint analysis.
  • Auto-commit system: selfdoc build, check, init, gen, and gen-data now auto-commit changed project files (hashes, generated docs, generated data). Disable with --no-commit. Uses safegit when available, falls back to git.
  • Directive token support in tokenizer: :::name arg / ::: blocks are recognized as structured tokens
  • SearchAction in WebSite JSON-LD on the homepage, enabling Google sitelinks search
  • GitHub Pages security headers: <meta http-equiv> tags for X-Content-Type-Options, X-Frame-Options, and Content-Security-Policy injected when deploy target is github-pages
  • WCAG contrast validation for user custom.css: SEO012 checks CSS variable overrides in docs/custom.css against theme backgrounds
  • High-contrast mode overrides: both themes override --link, --text-secondary, --sidebar-text, and --sidebar-active in prefers-contrast: more media query
  • Heading anchor IDs now deduplicate (appends -1, -2 for repeated headings) and preserve Unicode characters
  • Scrollspy correctly tracks headings when scrolling in both directions
  • Step guide detection tightened: keyword must appear at start of heading text, 200-char lookback (no more false positives on "Next Steps" or "Troubleshooting Steps")
  • API entry wrapping tightened: requires identifier-like heading and single-line code block (no more false positives on tutorial sections)
  • Prev/next links show directional labels ("Previous" / "Next") above page titles
  • Admonition icons use CSS mask-image technique, adapting correctly to dark mode
  • Diff highlighting uses +/- prefix symbols in addition to color
  • Collapsible section indicators replaced with 16x16px SVG chevrons (previously 8x12px CSS triangles)
  • Clean theme link color (#635bff) barely passed WCAG AA in light mode (4.70:1) and failed in dark mode (4.23:1). New color #5046e4 passes comfortably (6.29:1 light, 5.93:1 dark).
  • SEO lint false positives from fenced code blocks: heading counts (SEO001), heading level gaps (SEO002), empty alt text (SEO003), paragraph length (SEO007), empty sections (SEO011), and all other checks now use the tokenizer, making them immune to code block content
  • SEO007 false positives on directive-heavy pages: when a heading is followed by a :::directive block, the short-paragraph warning is suppressed
  • Statistics density check (SEO008) now evaluates prose content only, excluding code blocks
  • md_to_html() refactored from a 180-line line-walking loop into a clean tokenize-then-render pipeline
  • _redirects file is no longer generated (directory-index URLs don't need trailing-slash redirects)
  • _headers file is now only generated for cloudflare-pages deploy target
  • Auto-generated glossary page: collects all <dfn> terms site-wide into an alphabetical glossary with source links
  • Changelog auto-detection: CHANGELOG.md in project root is automatically included as a documentation page
  • selfdoc build --warn-only flag to treat lint warnings as non-fatal
  • Page progress indicator ("Page X of Y") between prev/next links
  • Current page title shown in the topbar on non-index pages
  • URL-triggered search: navigate to ?q=term to open search pre-filled with results
  • Meta description auto-generation: pages without frontmatter description now get <meta name="description"> auto-extracted from the first paragraph
  • Horizontal rule support: ---, ***, and ___ in Markdown now render as <hr>
  • Code tab sync no longer infinite-loops with 3+ tab groups sharing a language
  • Heading copy-to-clipboard shows a toast notification
  • Edit link opens in a new tab
  • OG description falls back to first paragraph when no frontmatter description
  • Each admonition type has a distinct background color
  • Focus indicators use :focus-visible throughout (keyboard-only, no mouse outlines)
  • Sidebar active link has a visible background highlight
  • Mobile sidebar traps focus within the overlay
  • Mobile sidebar closes on Escape key
  • Table rows highlight on hover
  • Cmd+K label adapts to platform (shows Ctrl+K on Windows/Linux)
  • "Last updated" date shown at the top of the page alongside breadcrumbs
  • Search "no results" message includes guidance ("Try different terms or browse the sidebar")
  • Feedback "No" response prompts for written feedback instead of just "Thanks"
  • Negative feedback provides a text input for follow-up
  • <summary> elements have :focus-visible outlines
  • <pre> elements have aria-label describing the code language
  • llms-full.txt includes page boundaries with title headings and path comments

#0.3.1

#Features

  • npm package renamed from selfdoc to selfdocumenting (npm blocks selfdoc due to similarity with abandoned self-doc package). Install via npm install -g selfdocumenting or npx selfdocumenting. The CLI command remains selfdoc.

#0.3.0

#Features

  • base_url is now a required field in selfdoc.json (previously optional)
  • Frontmatter description is now required on every page (auto-extraction removed); missing description is a build error
  • selfdoc build now fails on SEO lint warnings
  • Subdirectory-based nested nav groups with collapsible sidebar sections, localStorage persistence, and frontmatter overrides (nav_group, nav_order)
  • Configurable search trigger via search config field: "icon" (magnifying glass button), "bar" (text input with Cmd+K hint), or "hidden"
  • Functional feedback widget via feedback config field with webhook POST and Google Analytics event support
  • Atom feed generation (feed.xml) with auto-discovery <link> tag in <head>
  • Definition list syntax (term\n: definition) with glossary styling and DefinedTerm JSON-LD
  • Inline stat markup (==value==) producing semantic <data> elements
  • Code tabs for switching between language variants with localStorage persistence
  • Git branch auto-detection for edit links; configurable via branch config field
  • Rich OG card PNG generation with text overlay via predraw (optional dependency)
  • SEO lint framework with 15 rules covering headings, descriptions, images, contrast, and structured data
  • JSON-LD structured data: TechArticle, BreadcrumbList, WebSite, SoftwareSourceCode, Organization/Person, ItemList, DefinedTermSet
  • Open Graph and Twitter Card meta tags with og:locale, og:image:alt, and auto-generated social card images
  • robots.txt with explicit AI crawler permissions (GPTBot, ClaudeBot, PerplexityBot, etc.)
  • Visible "Last updated" dates with <time> elements, dateModified in JSON-LD, and sitemap lastmod
  • selfdoc check --ignore SEO007,SEO008 to suppress specific lint rules
  • selfdoc check --format json for machine-readable output
  • Color-coded selfdoc check output (green/yellow/red by severity)
  • New config fields: lang (BCP 47), author, twitter, branch, search, feedback
  • Sticky table headers no longer hide behind the fixed topbar
  • Copy button now always visible on code blocks (was hidden until hover, invisible on touch)
  • Fixed dark mode contrast for all accent colors
  • Fixed breadcrumb intermediate links pointing to non-existent directory index pages
  • Build-time Pygments syntax highlighting (replaced client-side highlight.js)
  • Build-time CSS, JS, and HTML minification with critical CSS inlining
  • Gzip and Brotli pre-compression of build output
  • Search JS externalized to search.js with lazy index loading
  • Conditional JS inclusion based on page content
  • ARIA labels on sidebar nav, TOC nav, and search dialog
  • Dynamic theme toggle ARIA label indicating current state
  • Roving tabindex on code tabs per WAI-ARIA pattern
  • Heading anchors visible on touch devices
  • Card-style prev/next navigation links
  • Print stylesheet: 2cm margins, forced light colors, hidden breadcrumbs, code wrapping
  • Security headers and trailing slash redirects for Cloudflare Pages
  • Edit link shown at both top and bottom of content area
  • llms.txt and llms-full.txt for AI documentation ingestion
  • selfdoc check reports undocumented public symbols when coverage is below 100%
  • lint_ignore config field for project-level lint rule suppression
  • Edit link and "Last updated" date no longer run together (flex layout with gap)
  • Search shows "No results" message instead of blank space
  • Search dialog closes when clicking a result link
  • Fixed code-block hover shadow invisible in dark mode
  • Table <caption> derived from preceding heading for screen readers
  • 44px minimum touch targets on all interactive elements
  • Admonition icons (distinct SVG per type: info, lightbulb, warning triangle, octagon, exclamation)
  • Styled generic <details>/<summary> in content
  • Styled standalone <dfn> tags outside glossary context
  • RSS feed link in site footer
  • Fragment highlight animation when navigating to #section URLs
  • Topbar truncates long project names with ellipsis

#0.2.0

#Features

  • Theme system with per-project theming via "theme" in selfdoc.json and optional docs/custom.css overrides
  • Syntax highlighting via highlight.js (light + dark themes)
  • Google-style docstring formatting (Args, Returns, Raises rendered as structured lists)
  • Heading hierarchy: directive expansions use h2/h3/h4 instead of injecting h1
  • Module name mangling (selfdoc.extractorsthon bug)
  • Nested _build/_build recursion when rebuilding
  • Deploy supports CF_ACCOUNT_ID and CF_PAGES_API_TOKEN env var names (remapped to wrangler's expected names)
  • Minimal theme: clean typography, dark mode, high-contrast, and reduced-motion variants (all auto-detected from OS preferences)
  • Top bar with project name and version badge
  • Heading anchor links for deep linking
  • CSS extracted to cacheable style.css instead of inlined per page

#0.1.0

#Features

  • Python, Go, TypeScript/JS extractors
  • Custom directive plugins
  • selfdoc check coverage analysis
  • HTML generation with responsive CSS
  • Deploy to Cloudflare Pages + GitHub Pages
  • SSE live reload in selfdoc serve
  • Code-aware static site generator
  • :::directive syntax for embedding code-extracted content
  • 5 built-in directives (module, schema, test, cli, config)