Configuration reference

All configuration lives in one file next to your content. Inkan looks for, in this order, inkan.config.ts, inkan.config.mjs, inkan.config.js and inkan.config.json in the folder it runs in (or in --root). No file at all is valid: every option has a default.

1
import { defineConfig } from '@tilaven/inkan';
2

3
export default defineConfig({
4
  title: 'Acme Decisions',
5
  url: 'https://decisions.acme.dev',
6
  repo: { url: 'https://github.com/acme/decisions', branch: 'main', provider: 'github' },
7
});

defineConfig only returns what you pass in; it exists so your editor can type-check the object against InkanConfig from lib/index.d.ts. In a .mjs or .js file you can use it the same way, or export a plain object. A .json file holds the same keys as the object and may carry a $schema key, which is accepted and dropped; the package does not ship a JSON schema file yet.

Every key is optional. Unknown keys are an error with a “did you mean” hint, so a typo cannot silently do nothing. Nested objects (repo, theme, footer, landing, git, codeRefs, og, sidebar, export, reviews, reviewers) are merged with the defaults key by key; docTypes and statuses replace the default maps as a whole. See Validate config and content at build time.

All paths are relative to the config file.

Site#

BASE_PATH matters in CI: the workflow and pipeline that init creates set BASE_PATH=/<repository name> for project pages. See Serve from a sub-path and GitHub and GitLab Pages.

Content paths#

See One folder per project, Number records with inkan new and Custom pages. The repository layout shows how the three folders fit together.

Look#

See Open Graph cards, Brand with logo and favicon, Theme with —inkan-* CSS tokens and Day and Stage themes.

Navigation#

1
export default defineConfig({
2
  navigation: [{ label: 'Handbook', href: '/handbook/' }],
3
  banner: { message: 'Decision review every Thursday, 14:00 in <b>#architecture</b>.', dismissible: true },
4
  footer: { copyright: '© Acme', links: [{ label: 'Status', href: 'https://status.acme.dev' }] },
5
  redirects: { '/sre/adr/0001': '/sre/adr/0001-define-slos/' },
6
  head: [{ tag: 'script', attrs: { defer: true, 'data-domain': 'decisions.acme.dev', src: 'https://plausible.io/js/script.js' } }],
7
});

See Header, banner, footer and redirects, Full-text search with pluggable providers and Comments under RFCs.

Extending#

See Override components and fill slots, MDX components without imports and Plugins with definePlugin.

Content model#

Default docTypes:

1
docTypes: {
2
  adr: { label: 'ADR', plural: 'Decisions', description: 'Architecture Decision Record' },
3
  rfc: { label: 'RFC', plural: 'Proposals', description: 'Request for Comments' },
4
}

Default statuses, with the two flags that give a status its meaning:

A StatusConfig has label (required), open (listed on the backlog, reviewBy is tracked), current (describes how things are now; gets periodic reviews unless reviews.statuses says otherwise), sticker (borrow the sticker of a built-in status, e.g. 'accepted') and color (sticker colour for a custom status without a built-in sticker).

A FieldConfig has type (text, number, boolean, date, enum, list or url; default text), label, description, values (required for enum, optional for list), required, filter (default true), column (table view column), unit (numbers only) and default (written by inkan new). Field names cannot be built-in front matter keys.

1
export default defineConfig({
2
  fields: {
3
    risk: { type: 'enum', values: ['low', 'medium', 'high'], column: true },
4
    cost: { type: 'number', unit: 'k€/year' },
5
  },
6
});

See Custom metadata fields, Turn issue keys into links, Record type comes from the folder and Configurable status lifecycle.

Sources#

Records kept in other repositories or folders, shown as one project each, exactly like a folder in contentDir.

1
export default defineConfig({
2
  sources: [
3
    { project: 'checkout', repo: 'git@github.com:acme/checkout.git', branch: 'main' },
4
    { project: 'search', dir: '../search-service', path: 'adrs' },
5
  ],
6
});

repo, branch and path must not start with -, and path must stay inside the source. inkan sync fetches repo sources into node_modules/.inkan/sources/<project>; build refreshes them (--offline keeps the cache) and dev fetches the missing ones. See Records from other repositories.

Git, code references, export and reviews#

1
export default defineConfig({
2
  git: { dates: true, authors: false },
3
  codeRefs: { include: ['src/**', 'infra/**'], marker: '@decision' },
4
  export: { statuses: ['accepted', 'implemented', 'deprecated'], title: 'Acme architecture decisions' },
5
  reviews: { every: '1 year', soon: 45 },
6
  notify: { channels: [{ type: 'slack', url: process.env.SLACK_WEBHOOK, projects: ['platform'] }] },
7
});

See Fill date and authors from git, Show status history from git, Reference records from code, Print and export, Notify chat when a decision is accepted and Review decisions on a schedule.

Landing#

Section names: stats adds the record counts to the hero and the lede, features shows the landing.features cards, projects lists the project cards, latest the newest records, content renders <contentDir>/_landing.md, agents lists the machine-readable endpoints. Any other name renders nothing.

1
export default defineConfig({
2
  landing: {
3
    actions: [
4
      { text: 'Quick start', link: '/quick-start/', variant: 'primary' },
5
      { text: 'All records', link: '/decisions/', variant: 'secondary' },
6
    ],
7
    sections: ['stats', 'content', 'projects', 'latest'],
8
  },
9
});

See Landing page from config.

Access#

Sign-in for the projects and paths that only some people may read. Without authentication nothing here has an effect and the build is one static dist/.

1
export default defineConfig({
2
  url: 'https://decisions.acme.dev',
3
  authentication: { type: 'gitlab', clientId: 'a1b2c3', allow: { groups: ['acme/platform'] } },
4
  protectedRoutes: ['/handbook/*'],
5
});

The build then writes the public site to dist/ and the full one to dist-protected/, and inkan serve enforces sign-in. See Sign-in and protected projects.

Resolved config#

Plugins and .astro pages see the resolved config, not your file: defaults applied, every path absolute, plus root, configFile, repoRoot (the Git top level, or root outside Git), contentPath (content folder relative to repoRoot, used in edit links) and templates (type to template text). sources is resolved too: each entry becomes a ResolvedSource with the clone or folder as root, the absolute contentDir, the derived web URL and provider. Its type is ResolvedConfig in lib/index.d.ts. See Data API and layouts.