# Inkan

> How to install, configure, extend and deploy inkan. Every feature is documented as an ADR, so this site is also a live example.

Types: adr (Architecture Decision Record), rfc (Request for Comments).
Statuses: draft, proposed, in-review, accepted, implemented, rejected, withdrawn, deprecated, superseded. Only "accepted"/"implemented" records describe the current state; "superseded" ones point to their replacement.
Full text of every record: https://useinkan.dev/llms-full.txt. Machine-readable index: https://useinkan.dev/decisions.json, link graph: https://useinkan.dev/graph.json.
Every link below points to the raw Markdown of the record; drop the ".md" suffix and add "/" for the HTML page.

## CLI (cli)

Install, scaffold, run and build a site from the command line.

- [CLI-ADR-0005: Change status and supersede from the CLI](https://useinkan.dev/cli/adr/0005-change-status-and-supersede-from-the-cli.md) [implemented]: How inkan status and inkan supersede edit front matter in place, which record references they accept, and what --dry-run shows.
- [CLI-ADR-0006: Import from log4brains, MADR and adr-tools](https://useinkan.dev/cli/adr/0006-import-from-log4brains-madr-and-adr-tools.md) [implemented]: How inkan import converts an existing ADR folder into numbered records with front matter, what it maps, what it skips and how to check the result.
- [CLI-ADR-0007: Check records in CI](https://useinkan.dev/cli/adr/0007-check-records-in-ci.md) [implemented]: What inkan check validates without building the site, how its output and exit codes work, and how the starter CI files run it.
- [CLI-ADR-0008: Notify chat when a decision is accepted](https://useinkan.dev/cli/adr/0008-notify-chat-when-a-decision-is-accepted.md) [implemented]: How inkan notify posts to Slack, Teams or a webhook when records move into a notified status, which commit it compares with, how channels are filtered, and how the starter CI files run it.
- [CLI-ADR-0009: Mark records reviewed from the CLI](https://useinkan.dev/cli/adr/0009-mark-records-reviewed-from-the-cli.md) [accepted]: How inkan reviewed writes the reviewed date and the next review into front matter, and how inkan reviews lists what is overdue or due soon.
- [CLI-ADR-0010: Answer a review from the CLI](https://useinkan.dev/cli/adr/0010-answer-a-review-from-the-cli.md) [implemented]: inkan rfc-review writes a reviewer's state into front matter in place, and --for lists the open records waiting on a person.
- [CLI-ADR-0001: Ship as an npm package with a CLI](https://useinkan.dev/cli/adr/0001-ship-as-an-npm-package-with-a-cli.md) [implemented]: How the inkan command runs a complete Astro site from inside the package against the content in your repository.
- [CLI-ADR-0002: Scaffold with init and npm create](https://useinkan.dev/cli/adr/0002-scaffold-with-init-and-npm-create.md) [implemented]: What inkan init and npm create @tilaven/inkan put into a repository, and how they behave in a folder that already has files.
- [CLI-ADR-0003: Number records with inkan new](https://useinkan.dev/cli/adr/0003-number-records-with-inkan-new.md) [implemented]: How inkan new picks the next number, builds the file name, fills a template and creates a project folder when needed.
- [CLI-ADR-0004: Validate config and content at build time](https://useinkan.dev/cli/adr/0004-validate-config-and-content-at-build-time.md) [implemented]: What Inkan checks in inkan.config and in front matter, how the errors read, and why a bad record fails the build.

## Writing records (authoring)

Projects, record types, front matter, statuses and Markdown.

- [AUTHORING-ADR-0009: Fill date and authors from git](https://useinkan.dev/authoring/adr/0009-fill-date-and-authors-from-git.md) [implemented]: When a record omits date or authors, the site takes them from the commit that added the file: what is inferred, how git authors become handles, and why shallow clones are skipped.
- [AUTHORING-ADR-0010: Reference records from code](https://useinkan.dev/authoring/adr/0010-reference-records-from-code.md) [implemented]: Point at a record from a code comment with @adr, and get the list of referencing files and lines on the record page, linked to GitHub or GitLab.
- [AUTHORING-ADR-0011: Review decisions on a schedule](https://useinkan.dev/authoring/adr/0011-review-decisions-on-a-schedule.md) [accepted]: Decided records come back up for review on a date or an interval: the reviewBy, reviewed and reviewEvery fields, the /reviews/ page, the check rule, the CLI commands and the MCP tool.
- [AUTHORING-ADR-0012: Custom metadata fields](https://useinkan.dev/authoring/adr/0012-custom-metadata-fields.md) [implemented]: Declare your own front matter fields per site or per project (risk, cost, data class), with types, validation, filters on the record index and values in decisions.json and the MCP server.
- [AUTHORING-ADR-0013: Review RFCs with reviewers](https://useinkan.dev/authoring/adr/0013-review-rfcs-with-reviewers.md) [implemented]: List reviewers in front matter, record each answer as pending, approved or changes-requested, and let Inkan work out whose move it is.
- [AUTHORING-ADR-0001: One folder per project](https://useinkan.dev/authoring/adr/0001-one-folder-per-project.md) [implemented]: How a folder with a small _project.yml becomes a team space with its own page, sidebar section and URL prefix.
- [AUTHORING-ADR-0002: Record type comes from the folder](https://useinkan.dev/authoring/adr/0002-record-type-comes-from-the-folder.md) [implemented]: Why adr/ and rfc/ folders define the record type, how to add your own types with docTypes and how numbers and refs are derived from file names.
- [AUTHORING-ADR-0003: Metadata in front matter](https://useinkan.dev/authoring/adr/0003-metadata-in-front-matter.md) [implemented]: Every field a record or page can carry in its YAML front matter, what each one drives on the site and how it is validated.
- [AUTHORING-ADR-0004: Configurable status lifecycle](https://useinkan.dev/authoring/adr/0004-configurable-status-lifecycle.md) [implemented]: The built-in statuses, what the open and current flags switch on, and how to define your own statuses with stickers and colours.
- [AUTHORING-ADR-0005: Optional author directory](https://useinkan.dev/authoring/adr/0005-optional-author-directory.md) [implemented]: How _authors.yml turns handles into names, teams and profile links, and why records work without it.
- [AUTHORING-ADR-0006: Link records by path](https://useinkan.dev/authoring/adr/0006-link-records-by-path.md) [implemented]: How supersedes, supersededBy and related reference other records, and how ordinary relative Markdown links work both on GitHub and on the site.
- [AUTHORING-ADR-0007: GitHub-flavoured Markdown with diagrams and math](https://useinkan.dev/authoring/adr/0007-github-flavoured-markdown-with-diagrams-and-math.md) [implemented]: Every Markdown feature a record can use, each one rendered live on this page: GFM, callouts, task lists, footnotes, Mermaid, KaTeX, Expressive Code and images.
- [AUTHORING-ADR-0008: Turn issue keys into links](https://useinkan.dev/authoring/adr/0008-turn-issue-keys-into-links.md) [implemented]: How the issueLinks option turns tracker keys such as PAY-123 or #42 in record text into links, with pattern, url and $1.
- [AUTHORING-RFC-0001: Fill date and authors from git](https://useinkan.dev/authoring/rfc/0001-fill-date-and-authors-from-git.md) [accepted]: A proposal to default a record's date and authors to the first commit that added the file when front matter leaves them out.

## Site (site)

Landing page, record index, timeline, backlog, decision graph, search and navigation.

- [SITE-ADR-0017: Sidebar order](https://useinkan.dev/site/adr/0017-sidebar-order.md) [implemented]: Records under each project in the sidebar are listed newest first by default; the sidebar.sort option switches to oldest first or record number order.
- [SITE-ADR-0016: Open decisions, periodic reviews and RFC reviews](https://useinkan.dev/site/adr/0016-open-decisions-periodic-reviews-and-rfc-reviews.md) [implemented]: Three pages list records with a date to watch. Which records each one shows, which question it answers, and where they overlap.
- [SITE-ADR-0008: Print and export](https://useinkan.dev/site/adr/0008-print-and-export.md) [implemented]: The /export/ page that prints every current decision as one document, the export option, and inkan export for a self-contained HTML file or an A4 PDF.
- [SITE-ADR-0009: README badges](https://useinkan.dev/site/adr/0009-readme-badges.md) [implemented]: The /badges/*.svg images and /badges/*.json shields.io endpoints every site serves, what each one counts, and the Markdown to put them in a README.
- [SITE-ADR-0010: Comments under RFCs](https://useinkan.dev/site/adr/0010-comments-under-rfcs.md) [implemented]: A discussion section below a record, off by default: giscus (GitHub Discussions), a GitLab issue read through the public API, or your own Astro component, switched per record type, status and record.
- [SITE-ADR-0011: Open Graph cards](https://useinkan.dev/site/adr/0011-open-graph-cards.md) [implemented]: The 1200×630 PNG card every record, project and the site get at /og/, how it is drawn at build time, and the og option that sets its theme or turns it off.
- [SITE-ADR-0012: Decision graph](https://useinkan.dev/site/adr/0012-decision-graph.md) [implemented]: What the /graph/ page draws, how supersedes and related links become arrows between project lanes, and the /graph.json export behind it.
- [SITE-ADR-0013: Show status history from git](https://useinkan.dev/site/adr/0013-status-history-from-git.md) [implemented]: Every record page lists its status changes from git history: the new status, date, author and a link to the commit, read with one git log per repository, with git.history to turn it off.
- [SITE-ADR-0014: RFC reviews page and Waiting on you](https://useinkan.dev/site/adr/0014-rfc-reviews-page-and-waiting-on-you.md) [implemented]: What the /rfc-reviews/ page lists, and how a static site shows each person the records that wait on them without a login.
- [SITE-ADR-0001: Landing page from config](https://useinkan.dev/site/adr/0001-landing-page-from-config.md) [implemented]: How the home page is assembled from the landing option in inkan.config.ts and an optional _landing.md, from a decision archive to a product page.
- [SITE-ADR-0002: Filterable record index](https://useinkan.dev/site/adr/0002-filterable-record-index.md) [implemented]: The /decisions/ page with its facet filters mirrored in the URL, the cards and table views, and the team pages at /<project>/.
- [SITE-ADR-0003: Timeline and backlog](https://useinkan.dev/site/adr/0003-timeline-and-backlog.md) [implemented]: What the /timeline/ and /backlog/ pages show, how open statuses and reviewBy dates drive the backlog, and how the pages stay light with many records.
- [SITE-ADR-0004: Authors and tags pages](https://useinkan.dev/site/adr/0004-authors-and-tags-pages.md) [implemented]: The /authors/ and /tags/ pages: who is listed, where names, teams and profile links come from, and how both pages feed the filterable index.
- [SITE-ADR-0005: Full-text search with pluggable providers](https://useinkan.dev/site/adr/0005-full-text-search-with-pagefind.md) [implemented]: One search palette with a choice of index behind it: the built-in Pagefind index, Algolia, Meilisearch, Typesense or your own provider module, plus the search.json the build writes for external services.
- [SITE-ADR-0006: Header, banner, footer and redirects](https://useinkan.dev/site/adr/0006-header-banner-footer-and-redirects.md) [implemented]: The site chrome you can configure: navigation links, the announcement banner, the footer, redirects for moved pages, repository-based Edit and New ADR links, and the previous/next pager.
- [SITE-ADR-0007: RSS feed and sitemap](https://useinkan.dev/site/adr/0007-rss-feed-and-sitemap.md) [implemented]: The /rss.xml feed of new records and the generated sitemap, and why the url option must be set for both.

## Theming (theming)

The OVERPRINT design, Day and Stage themes, tokens, logos and covers.

- [THEMING-ADR-0001: OVERPRINT design](https://useinkan.dev/theming/adr/0001-overprint-design.md) [implemented]: The design system behind every Inkan site: risograph inks on paper, die-cut status stickers, photocards, foil for records in force, self-hosted fonts and a print stylesheet.
- [THEMING-ADR-0002: Day and Stage themes](https://useinkan.dev/theming/adr/0002-day-and-stage-themes.md) [implemented]: How the light (Day) and dark (Stage) themes are chosen: the theme.default option, the reader's saved choice, the ?theme= query parameter, the system preference and the header toggle.
- [THEMING-ADR-0003: Theme with --inkan-* CSS tokens](https://useinkan.dev/theming/adr/0003-theme-with-inkan-css-tokens.md) [implemented]: The public theming API: every colour, font and shape is a --inkan-* custom property you override from your own CSS files listed in customCss.
- [THEMING-ADR-0004: Brand with logo and favicon](https://useinkan.dev/theming/adr/0004-brand-with-logo-and-favicon.md) [implemented]: How to put your own logo in the header and sidebar and your own favicon in the tab with the logo and favicon options.
- [THEMING-ADR-0005: Generated record covers](https://useinkan.dev/theming/adr/0005-generated-record-covers.md) [implemented]: Every record gets a risograph-style cover drawn at build time from its id, in an ink and motif that no other project shares, with plugin motifs of your own.

## Extending (extending)

Plugins, component overrides, custom pages and the data API.

- [EXTENDING-ADR-0006: Analytics with Plausible, Umami or Google Analytics](https://useinkan.dev/extending/adr/0006-analytics-plugin.md) [implemented]: A built-in plugin that adds page views and a few site events (search queries, page actions) to Plausible, Umami and Google Analytics 4, in the built site only.
- [EXTENDING-ADR-0001: Plugins with definePlugin](https://useinkan.dev/extending/adr/0001-plugins-with-defineplugin.md) [implemented]: How to package config changes, Markdown plugins, Vite plugins, Astro integrations, extra pages, cover motifs, head tags and navigation links into one reusable plugin.
- [EXTENDING-ADR-0002: Override components and fill slots](https://useinkan.dev/extending/adr/0002-override-components-and-fill-slots.md) [implemented]: Replace a built-in component such as the header or the record card with your own .astro file, or fill one of the empty slots without touching the rest.
- [EXTENDING-ADR-0003: Custom pages](https://useinkan.dev/extending/adr/0003-custom-pages.md) [implemented]: Add your own pages next to the records: Markdown and MDX files render through the docs layout, .astro files get full control, and the file path is the URL.
- [EXTENDING-ADR-0004: MDX components without imports](https://useinkan.dev/extending/adr/0004-mdx-components-without-imports.md) [implemented]: Register a set of components once in the config and use them in every MDX record and page without an import line.
- [EXTENDING-ADR-0005: Data API and layouts](https://useinkan.dev/extending/adr/0005-data-api-and-layouts.md) [implemented]: The inkan/data module and the two exported layouts: everything a custom page or a component override needs to read records, projects and authors.

## AI and data (ai)

llms.txt, decisions.json, Markdown copies and AGENTS.md.

- [AI-ADR-0005: MCP server for agents](https://useinkan.dev/ai/adr/0005-mcp-server-for-agents.md) [implemented]: inkan mcp serves records over the Model Context Protocol, from the content folder or a published site, so agents query with filters instead of reading llms-full.txt.
- [AI-ADR-0001: llms.txt and llms-full.txt](https://useinkan.dev/ai/adr/0001-llms-txt-and-llms-full-txt.md) [implemented]: Every build writes an index of all records for language models at /llms.txt and the full text of every record at /llms-full.txt.
- [AI-ADR-0002: decisions.json](https://useinkan.dev/ai/adr/0002-decisions-json.md) [implemented]: A typed JSON index of every record at /decisions.json, with status, dates, people, tags, lineage and links, for scripts, dashboards and agents.
- [AI-ADR-0003: Markdown copy of every page](https://useinkan.dev/ai/adr/0003-markdown-copy-of-every-page.md) [implemented]: Every record and page is also served as its original Markdown at the page URL plus .md, so people and agents can fetch the source without the HTML.
- [AI-ADR-0004: AGENTS.md for coding agents](https://useinkan.dev/ai/adr/0004-agents-md-for-coding-agents.md) [implemented]: A starter AGENTS.md tells coding agents how to read and write records, and the site serves it at /AGENTS.md next to llms.txt.
- [AI-RFC-0001: MCP server over decisions](https://useinkan.dev/ai/rfc/0001-mcp-server-over-decisions.md) [accepted]: Proposal: a small MCP server that lets agents query the archive through decisions.json with filters instead of reading llms-full.txt in full.

## Deploying (deploy)

Static output, GitHub and GitLab Pages, Docker, sub-paths and access control.

- [DEPLOY-ADR-0008: Cloudflare Workers](https://useinkan.dev/deploy/adr/0008-cloudflare-workers.md) [implemented]: How this documentation site is published to useinkan.dev: Workers static assets, docs/wrangler.jsonc and Cloudflare building from the repository.
- [DEPLOY-ADR-0005: Records from other repositories](https://useinkan.dev/deploy/adr/0005-records-from-other-repositories.md) [implemented]: The sources option pulls records kept in other repositories or folders into the site as one project each; inkan sync keeps a shallow clone of every repo source.
- [DEPLOY-ADR-0006: Protect the site at the edge](https://useinkan.dev/deploy/adr/0006-protect-the-site-at-the-edge.md) [implemented]: Keep a private archive private without touching the site: put oauth2-proxy, Cloudflare Access or the Pages access controls in front of the static output.
- [DEPLOY-ADR-0007: Sign-in and protected projects](https://useinkan.dev/deploy/adr/0007-sign-in-and-protected-projects.md) [implemented]: Let signed-in people see more than the public: add authentication and protectedRoutes to the config, mark projects protected, and run `inkan serve`, which builds a public and a members' site and enforces sign-in on the server.
- [DEPLOY-ADR-0001: Static HTML output](https://useinkan.dev/deploy/adr/0001-static-html-output.md) [implemented]: inkan build writes a complete static site to dist/, search index included, that any file server can host.
- [DEPLOY-ADR-0002: GitHub and GitLab Pages](https://useinkan.dev/deploy/adr/0002-github-and-gitlab-pages.md) [implemented]: The workflow files that inkan init writes: build every pull request, publish the default branch to GitHub Pages or GitLab Pages.
- [DEPLOY-ADR-0003: Docker and nginx](https://useinkan.dev/deploy/adr/0003-docker-and-nginx.md) [implemented]: The Dockerfile and nginx.conf that init writes: a two-stage image that builds the site and serves dist/ with the right redirects, 404 and cache headers.
- [DEPLOY-ADR-0004: Serve from a sub-path](https://useinkan.dev/deploy/adr/0004-serve-from-a-sub-path.md) [implemented]: The base option and the BASE_PATH variable: how to publish the site under /decisions/ or /<repo>/ with every link, redirect and search request pointing at the right place.
- [DEPLOY-RFC-0001: Aggregate records from many repositories](https://useinkan.dev/deploy/rfc/0001-aggregate-records-from-many-repositories.md) [accepted]: Proposal: let teams keep ADRs in their service repositories and have the build pull them into one site, one project folder per source.