MkDocs Tech Radar Plugin

A MkDocs plugin that generates an interactive Technology Radar based on the Zalando Tech Radar implementation.

This plugin helps engineering teams visualize and track their technology adoption, assessment, and decisions.

See live demo

Installation

Install the plugin using uv, pip, or your preferred Python package manager:

# Using uv
uv pip install mkdocs-tech-radar

# Using pip
pip install mkdocs-tech-radar

Configuration

Add the plugin to your mkdocs.yml:

Parameters

Option	Type	Default	Description
title_name	string	'Technology Radar'	Title for the radar
target_page	string	'tech-radar.md'	Page to embed the radar in
radars_folder	string	'radars'	Folder containing radar JSON files

Example

plugins:
  - tech-radar:
        title_name: 'Our Tech Radar'     # Optional: title for the radar (default: 'Technology Radar')
        radars_folder: 'radars'          # Optional: folder containing radar JSON files (default: 'radars')
        target_page: 'tech-radar.md'     # Optional: page to embed radar in (default: 'tech-radar.md')

Usage

Create one or multiple JSON files in a docs/radars/ folder for different radar versions:

docs/
  radars/
    2025-08-20.json
    2025-08-21.json
    2025-09-01.json

Note: Use date-based naming for optimal sorting:

• 2025-08-20.json - August 20, 2025 version
• 2025-09-01.json - September 1, 2025 version
• 2025-12-15.json - December 15, 2025 version

The plugin will:

• Automatically load all JSON files from the radars_folder
• Display a dropdown selector for switching between radar versions
• Default to the newest version (based on filename sorting)

Adding Radar to Your Documentation

Add the radar placeholder in your target markdown page:

# Tech Radar

The technology radar helps us track the technologies we use and evaluate emerging trends.

<!-- TECH_RADAR -->

Additional content can go here after the radar.

The <!-- TECH_RADAR --> placeholder will be replaced with the interactive radar visualization.

Recommended Workflow

1. Create a new radar file for each release/quarter
2. Copy the previous version as a starting point
3. Update entries with new technologies and movement indicators
4. The plugin automatically detects and makes it available
5. Commit the changes to your version control system

Radar File Structure

Each radar JSON file must contain these required fields:

Required Fields

• date (string): Radar date (e.g., "2025-08-20")
• quadrants (array): Four quadrant definitions
• rings (array): Four ring definitions with colors
• entries (array): Technology entries

Entry Properties

Each entry in the entries array must have:

• label (string): Technology name
• quadrant (0-3): Position in radar
  • 0: Languages & Frameworks
  • 1: Tools
  • 2: Platforms
  • 3: Techniques
• ring (0-3): Assessment level
  • 0: ADOPT
  • 1: TRIAL
  • 2: ASSESS
  • 3: HOLD
• moved (integer): Movement indicator
  • -1: Moved out (▼)
  • 0: No change (⬤)
  • 1: Moved in (▲)
  • 2: New (★)
• active (boolean): Whether entry is clickable/interactive
• link (string, optional): External URL
• description (string, optional): Technology description

Example Complete Radar File

Example radar file (docs/radars/2025-08-20.json):

{
  "date": "2025-08-20",
  "quadrants": [
    {"name": "Languages & Frameworks"},
    {"name": "Tools"},
    {"name": "Platforms"},
    {"name": "Techniques"}
  ],
  "rings": [
    {"name": "ADOPT", "color": "#5ba300", "description": "Technologies we have high confidence in"},
    {"name": "TRIAL", "color": "#009eb0", "description": "Worth pursuing with small risks"},
    {"name": "ASSESS", "color": "#c7ba00", "description": "Worth exploring with higher risks"},
    {"name": "HOLD", "color": "#e09b96", "description": "Proceed with caution or avoid"}
  ],
  "entries": [
    {
      "label": "React",
      "quadrant": 0,
      "ring": 0,
      "moved": 0,
      "active": true,
      "description": "A JavaScript library for building user interfaces",
      "link": "https://reactjs.org/"
    },
    {
      "label": "Vue.js",
      "quadrant": 0,
      "ring": 1,
      "moved": 1,
      "active": true,
      "description": "Progressive JavaScript framework",
      "link": "https://vuejs.org/"
    }
  ]
}

Customization

You can customize the radar appearance by modifying the radar files. The radar uses the Zalando color scheme by default:

• ADOPT: #5ba300 (green)
• TRIAL: #009eb0 (teal)
• ASSESS: #c7ba00 (yellow)
• HOLD: #e09b96 (red)

You can change these colors by modifying the rings array in your radar JSON files.

Check out the included example in the docs/ directory:

1. Build the documentation: uv run mkdocs build
2. Serve locally: uv run mkdocs serve
3. View the tech radar at: http://127.0.0.1:8000/tech-radar/

Credits

This plugin is based on the excellent Zalando Tech Radar implementation, which in turn is inspired by ThoughtWorks Technology Radar.

License

Apache License 2.0 - see LICENSE file for details.