Skip to content

ledger.mkdocs.adr.plugin

MkDocs plugin for ADR/MADR support.

This plugin automatically generates an ADR index page and applies custom templates to ADR pages following the MADR 4.0 template specification.

See: - https://adr.github.io/ for ADR documentation - https://adr.github.io/madr/ for MADR template documentation

Classes:

  • ADRPlugin –

    MkDocs plugin for ADR/MADR management.

Attributes:

LISTING_PAGE module-attribute 

LISTING_PAGE = '---\ntemplate: adr/list.html.jinja\n---\n# Architectural Decision Records\n'

RE_H1 module-attribute 

RE_H1 = compile('^#\\s+.*\\n', MULTILINE)

ADRPlugin

Bases: BasePlugin

MkDocs plugin for ADR/MADR management.

Methods:

  • on_config –

    Normalize ADR path relative to docs directory.

  • on_env –

    Register Jinja filters for ADR rendering.

  • on_files –

    Add virtual ADR index file.

  • on_page_context –

    Inject ADR list into context for the index page.

  • on_page_markdown –

    Process ADR pages: set metadata and strip first H1.

  • on_page_read_source –

    Provide content for virtual ADR index page.

Attributes:

config_scheme class-attribute instance-attribute 

config_scheme = (('path', Type(str, default='adr')),)

on_config 

on_config(config)

Normalize ADR path relative to docs directory.

Source code in ledger/mkdocs/adr/plugin.py 
41
42
43
44
45
46
47
48
49
50
def on_config(self, config):
    """Normalize ADR path relative to docs directory."""
    docs_dir = Path(config["docs_dir"])
    # Always treat path as relative to docs_dir
    self.adr_dir_rel = Path(self.config["path"])
    self.adr_dir_abs = docs_dir / self.adr_dir_rel
    self.adr_dir_abs.mkdir(parents=True, exist_ok=True)
    # Store docs_dir for base_path calculations
    self.docs_dir = docs_dir
    return config

on_env 

on_env(env, config, files)

Register Jinja filters for ADR rendering.

Source code in ledger/mkdocs/adr/plugin.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def on_env(self, env, config, files):
    """Register Jinja filters for ADR rendering."""

    def adr_url(doc):
        name = Path(doc.file_path).name
        slug = name[:-3] if name.endswith(".md") else name
        if not slug:
            return ""
        if config.get("use_directory_urls", True):
            return f"/{self.adr_dir_rel}/{slug}/"
        return f"/{self.adr_dir_rel}/{slug}.html"

    env.filters["adr_url"] = adr_url
    return env

on_files 

on_files(files, config)

Add virtual ADR index file.

Source code in ledger/mkdocs/adr/plugin.py 
52
53
54
55
56
57
58
59
60
61
62
def on_files(self, files, config):
    """Add virtual ADR index file."""
    index_path = f"{self.adr_dir_rel}/index.md"
    index_file = File(
        path=index_path,
        src_dir=config["docs_dir"],
        dest_dir=config["site_dir"],
        use_directory_urls=config["use_directory_urls"],
    )
    files.append(index_file)
    return files

on_page_context 

on_page_context(context, page, config, nav)

Inject ADR list into context for the index page.

Source code in ledger/mkdocs/adr/plugin.py 
71
72
73
74
75
76
def on_page_context(self, context, page, config, nav):
    """Inject ADR list into context for the index page."""
    index_path = f"{self.adr_dir_rel}/index.md"
    if page.file.src_uri == index_path:
        context["adrs"] = self._scan_adrs()
    return context

on_page_markdown 

on_page_markdown(markdown, page, config, files)

Process ADR pages: set metadata and strip first H1.

Source code in ledger/mkdocs/adr/plugin.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def on_page_markdown(self, markdown, page, config, files):
    """Process ADR pages: set metadata and strip first H1."""
    if not self._is_adr_page(page):
        return None

    if page.file.abs_src_path:
        adr = parse_adr(Path(page.file.abs_src_path), self.docs_dir)
        page.meta["adr"] = adr
        page.meta["template"] = "adr/page.html.jinja"

        if adr.title:
            page.title = adr.title

        markdown = RE_H1.sub("", markdown, count=1)

    return markdown

on_page_read_source 

on_page_read_source(page, config)

Provide content for virtual ADR index page.

Source code in ledger/mkdocs/adr/plugin.py 
64
65
66
67
68
69
def on_page_read_source(self, page, config):
    """Provide content for virtual ADR index page."""
    index_path = f"{self.adr_dir_rel}/index.md"
    if page.file.src_uri == index_path:
        return LISTING_PAGE
    return None