Authoring Guide
The frontmatter and markdown conventions every note in this knowledge base follows.
~2 min read updated Jul 17, 2026 Meta
#meta #conventions #markdown #authoring
Conventions for writing notes, kept here so the rules live where they're used. When in doubt, copy an existing note and adapt it.
Frontmatter
Every note starts with a frontmatter block:
---
title: Eloquent Relationships # required. Sentence case, no trailing period
description: One sentence, used in cards, search and SEO. # required
tags: [laravel, eloquent, database] # 2–6, lowercase-kebab, singular nouns
keywords: [hasMany, eager loading] # optional search synonyms, never displayed
category: Laravel # optional; defaults to the folder name
createdAt: 2026-07-17 # required, YYYY-MM-DD
updatedAt: 2026-07-17 # required, bump on every meaningful edit
featured: false # optional; shows on the homepage. Keep to ~6 site-wide
draft: false # optional; hidden in production, visible in dev
---
readingTime is calculated automatically at build time — never set it by hand.Files & folders
- Notes are markdown files under
content/. - Numeric prefixes (
1.intro.md,2.setup.md) set order and are stripped from the URL. Renumbering reorders the sidebar without changing links. - A folder's title and icon come from its
.navigation.yml. - A file prefixed with
-is excluded entirely — use it for scratch drafts.
Markdown & MDC features
The full set is demonstrated on the Markdown Showcase. The essentials:
| Feature | Syntax |
|---|---|
| Callouts | ::note, ::tip, ::warning, ::caution |
| Code block | ```ts [filename.ts]{2-4} (language, optional filename, line highlights) |
| Tabbed code | ::code-group around several fenced blocks |
| Tabs | ::tabs with ::tabs-item{label="..."} |
| Collapsible | ::collapsible{name="..."} |
| Steps | ::steps{level="3"} around ### headings |
| Diagram | a ```mermaid fenced block |
| Video | ::video-embed{src="https://youtube.com/watch?v=..."} |
| Keyboard | :kbd{value="meta"} |
Writing style
Lead with the useful thing. A note is a reference you'll read while working, not
an essay — put the command, the pattern or the answer first, and the background
after.
- One
#H1 at most (or none — the title comes from frontmatter). - Link related notes with root-relative paths:
[naming](/dev/clean-code/naming-things). - Prefer a short, real example over a long explanation.
Meta
How this knowledge base itself is built and maintained.
Markdown Showcase
Every formatting feature this knowledge base supports, on one page — a living reference and rendering test.