MkDocs ADR Plugin

A plugin for MkDocs that adds a floating button to create Architecture Decision Records (ADR) directly from the documentation UI.

Features

• 🔘 Floating button with a modal form
• ✏️ Edit template content before saving
• 🔢 Automatic numbering and date substitution
• 📁 Select template from docs/adr/templates/
• 🌐 Works with any MkDocs theme
• 🐧 Cross‑platform (Linux, macOS, Windows)

Installation

pip install mkdocs-adr-plugin

Usage

Start the server

From your project root (where mkdocs.yml is located), run:

mkdocs-adr

This starts both the ADR API (FastAPI) and mkdocs serve in one terminal.

Create an ADR

1. Open http://localhost:8000
2. Click the + button in the bottom‑right corner
3. Fill in the form:
   • Slug – filename part (only letters, digits, hyphen, underscore)
   • Title – full ADR title (optional, defaults to slug)
   • Template – choose one from docs/adr/templates/
   • Content – edit the Markdown content as needed
4. Click Save – the new ADR file will be created in docs/adr/ and the page reloads.

Configuration in mkdocs.yml

plugins:
  - adr_plugin:
      api_url: http://localhost:8765   # optional, default is this

Custom Templates

Put .md files inside docs/adr/templates/. You can use the following placeholders:

• {{NUMBER}} – auto‑incremented number (0001, 0002…)
• {{TITLE}} – title from the form
• {{DATE}} – current date (ISO 8601)

The default template is created automatically on first run.

License

MIT