Inkan
↑↓ move↵ open
GitHub

Page

What is Inkan

A docs site for Architecture Decision Records and RFCs, built from the Markdown in your repository.

Inkan turns a folder of Markdown files into a searchable website for Architecture Decision Records (ADR) and RFCs. You keep writing records in your repository, next to the code and under the same review process. Inkan adds the site: one folder per team, record numbers, statuses, a timeline, a backlog, a decision graph, full-text search, a print export and machine-readable exports for AI tools. It also adds the tooling around the records: a check for CI, commands that change statuses and supersede records, an importer for existing ADR folders, records pulled from other repositories and an MCP server for agents.

It is a CLI with a complete site inside the npm package. Your repository holds only content and one config file.

Who it is for#

  • Engineering organisations that want one place for the decisions of every team (SRE, Payments, Platform, DBRE and so on), without one wiki page per team drifting apart.
  • Teams that already write ADRs as Markdown and want them published without building a site themselves.
  • People who use coding agents and want the decisions available as llms.txt, decisions.json, graph.json and AGENTS.md.

You need Node.js 22.22 or newer, a Git repository and a few minutes. See the quick start.

How it works#

your repository                          inkan (npm package)
inkan.config.ts   ─┐               bin/cli.mjs        dev | build | preview | init
decisions/               ├──────────►    lib/commands/      new | status | supersede | import | check | sync | export | mcp
                         │               app/               the Astro site, config injected as a virtual module
  sre/_project.yml       │               templates/         adr.md, rfc.md for `inkan new`
  sre/adr/0001-….md      │               starter/           files that `init` copies
  sre/rfc/0001-….md     ─┘
                                         dist/              static HTML, CSS, search index

inkan build reads your config, validates every record’s front matter and writes plain HTML to dist/. There is no server and no database: host the output on GitHub Pages, GitLab Pages, S3 or nginx.

Features#

Every feature of Inkan is documented as a record on this site. The record explains why the feature exists, what was decided and how to use it.

CLI#

Writing records#

Site#

Theming#

Extending#

AI and data#

Deploying#

Ideas that are not built yet are RFCs with status: proposed. They show up on the Open decisions page of this site.

Compared with similar tools#

Zudoku is a docs framework for API references: a CLI, a site inside the package, one config file, and your repository holds only content. Inkan follows the same model, but the content model is decisions instead of OpenAPI, so it knows about projects, record types, numbers, statuses and the links between records.

log4brains is the closest tool in purpose. It also publishes ADRs from Markdown and gave Inkan many of its ideas: numbered files, a timeline, superseding. Inkan differs in a few places: metadata lives in front matter instead of Markdown headings, many projects share one site through folders, and the output includes files made for AI agents. Ideas that are not built yet are written up as RFCs next to the decisions.

About this site#

This site is built with Inkan from the docs/ folder of the Inkan repository. The config is docs/inkan.config.ts, the records are in docs/decisions/, and every page you read here renders the way your own records will.

Next: the quick start, then the repository layout, the configuration reference and the front matter reference.