Skip to content
house-rules

Write a docs page

Skill write-a-docs-page, from skills/write-a-docs-page/SKILL.md. An agent loads that file as a skill. This page shows the same text.

The docs site lives in site/. Some pages are hand-written. Others are generated from the code, and nobody edits them by hand. Pick the kind first.

1. Choose the kind

Section titled “1. Choose the kind”
Kind Where Edit
Start, guide, reference site/src/content/docs/{start,guides,reference}/<slug>.md by hand
Home site/src/content/docs/index.md by hand
Rule site/src/content/docs/rules/<tool>/<rule>.md generated from packages/rules
Skill site/src/content/docs/skills/<name>.md generated from skills/<name>/SKILL.md

To change a rule page, change its source: the rules table in packages/rules/README.md, the rule’s meta in packages/rules/src/, or its doc in packages/rules/docs/. To change a skill page, change the SKILL.md. A new skill folder gets a page by itself. Then run:

Terminal window
pnpm --filter @house-rules/site generate

Commit the regenerated pages with the source change. pnpm test fails while a generated page is stale.

2. Write a hand-written page

Section titled “2. Write a hand-written page”
  1. Name the file in kebab-case. The path is the URL: guides/the-fence.md is /guides/the-fence/.
  2. Use .md, not .mdx. The raw copies and llms-full.txt are built from the Markdown, and ESLint checks only .md.
  3. Give it frontmatter with title, a one-sentence description, and sidebar.order. The description goes into llms.txt.
  4. Do not repeat the title as an # heading. Start with ##.
  5. Say one thing per page. Link to the source file instead of copying a long passage from it.
  6. Use the words in CONTEXT.md. If AGENTS.md says it, cite it; do not restate the law in other words.
---
title: The fence
description: The git hook, the harness hooks, and the command policy that stop an agent from skipping the checks.
sidebar:
  order: 3
---
Section titled “3. Link by relative path”

Link to another page by the relative path of its .md file, and to a repo file by its relative path from the page:

See [the fence](../guides/the-fence.md) and [`AGENTS.md`](../../../../../AGENTS.md).

ESLint’s no-broken-relative-links checks each path against the files git tracks. At build time a page link becomes its route, and a repo link becomes a GitHub URL. Do not write /guides/the-fence/ by hand: nothing checks it.

4. Use a visual when it explains something

Section titled “4. Use a visual when it explains something”
Need Use
Flow or layers a fenced text block with a box or arrow diagram
Choices or facts per item a table
Files a shallow tree
Steps the reader does a numbered list with checkboxes

Keep diagrams under 100 columns.

5. Prove it

Section titled “5. Prove it”
Terminal window
pnpm --filter @house-rules/site build
pnpm check
pnpm test

The build writes site/dist/llms.txt, site/dist/llms-full.txt, and site/dist/<path>.md for your page. Open the .md copy and check that its links point at https://stack.kubaszwajka.com/...md or GitHub.

The theme lives in site/src/styles/theme.css. A page never sets colors or fonts itself.

All skills