0001: One folder per project

Context#

A company keeps decisions for many teams: SRE, Payments, Platform, DBRE. Each team wants its own list, its own owners and its own numbering, but nobody wants to register teams in a config file and keep that file in sync with the folders. The repository layout already says which team a record belongs to.

Decision#

A project is a top-level folder inside the content folder (decisions/ by default). A _project.yml in that folder gives it a name, a description, owners and links. The folder name is the project id and the first URL segment of everything in it. A folder without _project.yml still works: it is listed under its folder name.

Any Markdown file in a project folder that is not a record becomes a page in that project’s sidebar section. Files and folders whose name starts with _ are never pages.

How to use it#

The folder#

1
decisions/
2
  sre/
3
    _project.yml              project metadata
4
    index.md                  optional intro shown on the team page
5
    adr/0001-define-slos.md   records, see "Record type comes from the folder"
6
    rfc/0001-error-budget.md
7
    guides/on-call.md         any other page
8
    _drafts/ideas.md          ignored: starts with "_"

inkan new adr sre "Title" creates sre/_project.yml with a placeholder name when the folder is new. Fill it in afterwards.

_project.yml#

1
name: "SRE"
2
description: "Reliability, on-call and the numbers we promise."
3
icon: activity
4
ink: c
5
motif: rings
6
owners: [marek, ania]
7
order: 10
8
links:
9
  - label: Runbooks
10
    url: https://runbooks.acme.example
11
  - label: On-call guide
12
    url: /sre/guides/on-call/

Built-in icon names: search, sun, moon, menu, x, chevron-right, arrow-right, arrow-left, external, pencil, rss, file-plus, book, heart, activity, database, server, cloud, settings, credit-card, shield, users, layers, tag, clock, inbox, list, home, sparkles, github, gitlab. An unknown name falls back to book.

.yaml works as well as .yml. The build fails when a field has the wrong type, for example an ink outside the six letters, or when motif names a motif nobody registered.

The team page#

Every project gets a page at /<folder>/. It shows the owners, one counter per record type, “New ADR” and “New RFC” buttons (when repo is configured, they open your repository’s web editor with the next number and the template filled in), the links, the intro and the records as cards.

The intro is index.md or README.md in the project folder. index.md wins when both exist. It is rendered as part of the team page and does not get a page of its own. Its front matter needs only title:

1
---
2
title: SRE
3
---
4
We run the platform. Decisions here cover alerting, SLOs and incident process.

Other pages in a project#

Any .md or .mdx file in a folder that is not a record type is a plain page. It appears in the sidebar under the project, after the record groups, sorted by the order front matter field (lowest first, default 0) and then by title.

1
---
2
title: On-call guide
3
description: Who gets paged, when, and what to do.
4
order: 1
5
---

Pages show an “Edit on github” link and the date of the last commit that touched the file when the site is built inside a git checkout.

Markdown files at the root of the content folder (not in any project) are listed at the top of the sidebar, also sorted by order. This site uses them for its own guides.

URL mapping#

The URL is the file path without the extension, lower-cased, with a trailing slash:

Path segments are slugified the way GitHub slugs headings: spaces become -, punctuation is dropped. A slug field in front matter replaces the whole path. The project folder is slugified the same way, and that slug is the project’s id everywhere: a folder Ops Plans/ is the team ops-plans, at /ops-plans/, with refs like OPS-PLANS-ADR-0001. The old address /projects/<folder>/ redirects to /<folder>/.

Project folders cannot use the names of built-in pages: decisions, timeline, backlog, graph, authors, tags, projects. The build reports the collision.

Consequences#

• Adding a team is creating a folder. Nothing in inkan.config.ts changes.
• The folder name is part of every URL and of every ref (SRE-ADR-0007). Renaming a folder moves all its records; use redirects in the config for the old paths.
• _project.yml is optional, so a half-configured repository still builds. The downside is that a typo in the file name (project.yml without the underscore) is silently ignored and the folder shows up under its raw name.
• icon is validated but not displayed by the built-in components. Treat it as a hook for your own overrides.