A GitHub Action that deploys your Architecture Decision Records as a beautiful website using GitHub Pages.

Check out this repository's page.

• 🚀 Get started by just adding a single GitHub Actions workflow
• 🎨 Modern dark theme
• 📱 Mobile responsive
• 🔍 Full-text search across ADR titles and content
• 📊 Dashboard with ADR statistics (total count, status breakdown)
• 🕒 Recently added ADRs section on homepage
• ⚙️ Customizable sidebar (show/hide dates, toggle title wrapping)

Go to Settings → Pages and set source to "GitHub Actions"

Create .github/workflows/adr-explorer-deploy.yml:

name: Deploy ADR Explorer

on:
  push:
    paths: ["doc/adr/**"] # NOTE: Change this if you place your adrs elsewhere
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: lugen4ro/adr-explorer@main
        with:
          adr-path: "doc/adr" # NOTE: Change this if you place your adrs elsewhere
      - uses: actions/deploy-pages@v4

Put your markdown adr files in doc/adr/:

# ADR-001: Database Choice

## Status

Accepted

## Decision

We will use PostgreSQL...

The supported format is mainly the one of adr-tools.

Your site will be live at https://username.github.io/repository-name/ For example for this repository it is https://lugen4ro.github.io/adr-explorer/

- uses: lugen4ro/adr-explorer@main
  with:
    adr-path: "doc/arch_decisions"

• Proposed
• Accepted
• Deprecated
• Superseded
• Rejected

• Explore ADRs in modern UI
• Support ADR format of adr-tools
• Support images, syntax colored code snippets & Mermaid charts
• Support non-English ADRs (Mainly Japanese)
• Support date extraction from filename
• Support nested ADR directory structures
• Free-text search
• Support realtive links

MIT