KB / meta / kb-content-conventions

KB Content Conventions

Frontmatter schema, category slugs, tag rules, and article length guidelines for apps/kb/content articles.

Updated 2026-05-26
kbmetafrontmatterconventions
raw .md

KB Content Conventions

These rules govern how articles in apps/kb/content/ are written and structured.

Frontmatter schema

---
title: "string"
category: "category-slug"
tags: ["tag1", "tag2"]
links: ["other-article-slug", ...]
summary: "one-sentence summary for index + llms.txt"
updated: "YYYY-MM-DD"
---

All fields are required.

Categories (exact slugs)

Slug Covers
infrastructure Cloudflare, deploy, WASM build, CI
design-system design tokens, dark mode, shadcn migration
apps per-app overviews
agents duyetbot scope, agent refactor, autonomous workflows
data-pipeline data sync, ClickHouse, CCUsage
workflows commit/push/deploy, commitlint, test cache
decisions architectural decisions
meta about the KB, how to contribute

Tags

  • Lowercase single words or hyphenated: dark-mode, wasm, cloudflare
  • 2–5 tags per article
  • Match to the concrete tools, patterns, or app names involved
  • List slugs of related articles (filename without .md)
  • Each article should link to 2–5 others
  • Bidirectional links are not required on both ends — the pipeline computes incoming links from outgoing

summary

  • Single sentence, ≤140 characters
  • Goes into /llms.txt — make it scannable and specific
  • Bad: "An article about the blog."
  • Good: "apps/blog uses WASM markdown rendering and isomorphic readPublicJson for 393 SSG pages."

Article length

50–200 lines. Lead with # Title, then a 2–3 sentence intro, then sections. Cite concrete file paths and commit SHAs when useful.

Slugs

Lowercase kebab-case. Filename = slug. Example: infrastructure/cloudflare-rocket-loader.md.

Tone

Terse and technical. No marketing language. No "comprehensive", "elaborate", "extensive". Write like internal documentation.

Back to KB