0003: Custom pages

Context#

A decision site needs a few pages that are not decisions: a handbook on how to write records, an on-call page, a statistics dashboard. Markdown files inside the content folder already become pages, but they are grouped under a project and listed in the sidebar as part of the archive. Some pages belong to the site, not to a team, and some need code, not prose.

Decision#

A folder outside the content directory, pagesDir (default pages), holds your own pages. The file path is the URL. .md and .mdx files render through the same route and layout as the records, with the site’s Markdown features and your MDX components. .astro files are injected as routes and can import the package’s layouts and data helpers. Files and folders starting with _ are ignored.

How to use it#

1
pages/
2
  handbook.md          -> /handbook/
3
  on-call.mdx          -> /on-call/
4
  stats.astro          -> /stats/
5
  guides/index.md      -> /guides/
6
  guides/review.md     -> /guides/review/
7
  _drafts/ideas.md     -> ignored

Markdown and MDX pages#

Front matter needs a title; description and draft are optional. Nothing else is read, so a page cannot have a status or authors; that is what records are for.

1
---
2
title: Decision handbook
3
description: How Acme writes, reviews and retires architecture decisions.
4
---
5

6
## When to write a record
7

8
Write an **ADR** when a choice is hard to reverse. Write an **RFC** when you want feedback before deciding.

The page renders in the reading layout with the eyebrow “Page”, a table of contents in the right rail, an “Edit on github” link when repo is configured, and a “Last updated” date from git. It is indexed by search, listed in a ## Pages section of /llms.txt, and served as raw Markdown at /handbook.md.

Markdown pages are not added to the sidebar. Link them from the header with navigation or from _landing.md:

1
navigation: [{ label: 'Handbook', href: '/handbook/' }],

Astro pages#

An .astro file becomes a route at its path. It can use the two layouts the package exports and the data API:

1
---
2
import Page from '@tilaven/inkan/layouts/Page';
3
import { countBy, getDecisions } from '@tilaven/inkan/data';
4

5
const decisions = await getDecisions();
6
const byStatus = countBy(decisions.map((d) => d.status ?? 'none'));
7
---
8
<Page title="Records by status" accent="status" eyebrow="Custom page" lede="Live counts computed at build time.">
9
  <table>
10
    <thead><tr><th>Status</th><th>Records</th></tr></thead>
11
    <tbody>{byStatus.map(([status, count]) => <tr><td>{status}</td><td>{count}</td></tr>)}</tbody>
12
  </table>
13
</Page>

Dynamic routes work too: pages/by-tag/[tag].astro with a getStaticPaths() export, as in any Astro project.

Layouts#

accent is the word of the title to underline. ink is a project ink class such as ink-c. Both layouts take a default slot and a lede slot for markup under the title; Page adds a head slot inside the page head, Docs adds rail and rail-end slots. See Data API and layouts.

Rules and checks#

• A page whose route matches a built-in page (/decisions/, /timeline/, /authors/, /rss.xml, a project folder, …), a record, a redirect source or another page fails the build with inkan: page routes must be unique. A route with a parameter only warns.
• Adding or removing a file in pagesDir restarts the dev server so the routes are recomputed. Edits hot-reload.
• pages/index.astro would claim /, which the landing page owns; it fails the collision check.
• Pages in pagesDir are not records: no status, no number, no place in decisions.json or the timeline.

Consequences#

• Prose pages cost one Markdown file; code pages cost one .astro file. Both live outside the archive and do not disturb numbering or statistics.
• Markdown pages are reachable only through links you add, by design. A page that should sit in a team’s sidebar belongs in decisions/<project>/ instead.
• .astro pages use Astro directly, so Astro’s API surface and its upgrades become part of your site.
• Collisions fail the build rather than silently shadowing a built-in page.