#Theme Showcase

#Typography

#Headings

#Heading Level 1

#Heading Level 2

#Heading Level 3

#Heading Level 4

#Heading Level 5

#Heading Level 6

#Inline Elements

This paragraph contains bold text, italicized text, and inline code like parse_directives(). You can also use external links and internal links to navigate the documentation.

selfdoc resolves :::directive blocks in Markdown templates into content extracted from source code. It supports Python, Go, and TypeScript/JavaScript through language-specific extractors that handle all five built-in directives: module, schema, test, cli, and config.

#Lists

#Unordered List

• Directive parser -- state machine that tracks fenced code blocks
  • parse_directives extracts directive blocks from Markdown
  • resolve_directives replaces directives with resolver output
• Resolver -- dispatches to the correct language extractor
  • Custom directives from selfdoc.json are checked first
  • Falls back to built-in language-specific extractors
• Build pipeline -- scans, resolves, converts, and writes output
• HTML converter -- built-in Markdown-to-HTML with no dependencies

#Ordered List

1. Create a selfdoc.json configuration file in your project root
2. Write Markdown templates in your docs/ directory
3. Add :::directive blocks where you want code content injected
4. Run selfdoc build to generate your documentation site

#Step Guide

1. Install selfdoc using pip install selfdoc or npm install -g selfdoc. The npm package is a thin Node wrapper that delegates to python3 -m selfdoc.
2. Initialize your project with selfdoc init. This creates a selfdoc.json config file and a docs/ directory with a starter template.
3. Run the development server with selfdoc serve. It uses SSE-based live reload with mtime polling so you see changes instantly as you edit templates.

#Code

#Plain Code Block

selfdoc build --output _site
selfdoc serve --port 8080
selfdoc check --coverage

#Code with Language

from selfdoc.directives import parse_directives, resolve_directives
from selfdoc.resolver import make_resolver

def build_docs(config):
    """Build documentation from Markdown templates."""
    resolver = make_resolver(config)
    for template_path in config.docs_dir.glob("*.md"):
        content = template_path.read_text()
        resolved = resolve_directives(content, resolver)
        output = md_to_html(resolved)
        write_output(output, template_path)

#Diff Highlighting

 def resolve_directives(content, resolver):
-    directives = parse_directives(content)
-    for directive in directives:
-        content = content.replace(directive.raw, resolver(directive))
+    directives = list(parse_directives(content))
+    for name, arg, body in directives:
+        replacement = resolver(name, arg, body)
+        content = content.replace(body, replacement)
     return content

#Code Annotations

def _slugify(text):
    text = re.sub(r"<[^>]+>", "", text)  1
    text = text.lower()
    text = text.replace(" ", "-")  2
    text = re.sub(r"[^a-z0-9-]", "", text)  3
    return text.strip("-")

#Code Tabs

import ast

def extract_module(source_path: str) -> str:
    """Extract module-level docstring using the ast module."""
    tree = ast.parse(open(source_path).read())
    return ast.get_docstring(tree) or ""

package extractor

import "go/doc"

// ExtractModule returns the package-level documentation comment.
func ExtractModule(pkgPath string) string {
    pkg, _ := doc.NewFromFiles(fset, files, pkgPath)
    return pkg.Doc
}

import * as ts from "typescript";

export function extractModule(sourcePath: string): string {
  const sourceFile = ts.createSourceFile(
    sourcePath,
    readFileSync(sourcePath, "utf-8"),
    ts.ScriptTarget.Latest,
  );
  // Extract leading comment from the source file
  return getLeadingComment(sourceFile) ?? "";
}

#Long Code Block

def resolve_directives(content: str, resolver: Callable[[str, str, str], str], source_paths: list[str] | None = None) -> str:
    """Replace all :::directive blocks in content with resolver output. Handles nested fenced code blocks correctly."""
    directives = list(parse_directives(content))
    for name, arg, body in sorted(directives, key=lambda d: content.index(d[2]), reverse=True):  # reverse to preserve offsets
        replacement = resolver(name, arg, body)
        content = content[:content.index(body)] + replacement + content[content.index(body) + len(body):]
    return content

#Blocks

#Blockquote

selfdoc keeps your documentation in sync with your code. When you change a function signature, the docs update automatically on the next build. No more stale examples or outdated API references.

#Nested Blockquote

selfdoc extracts documentation from source code automatically.

The key insight is that code IS the documentation. By extracting directly from source, docs never go stale.

#Blockquote with Code

To use a custom directive, add it to your selfdoc.json:

{
  "directives": {
    "changelog": "scripts/extract_changelog.py"
  }
}

#Admonitions

#Table

#Wide Table

#API Entry Cards

def parse_directives(content: str) -> list[tuple[str, str, str]]

def resolve_directives(content: str, resolver: Callable) -> str

def md_to_html(text: str) -> str

#Glossary

#Collapsible Sections

def build(dir_path: str = ".") -> dict[str, str]:
    config = load_config(dir_path)
    resolver = make_resolver(config)
    html_files = generate_html(markdown_files, config)
    return html_files

#Images

#Search Dialog

Press Cmd+K (or Ctrl+K) to open the search dialog, or click the button below to open it manually for preview.

Open Search Dialog

#Page Not Found