Contributing Guide
2 min read
This guide keeps notes consistent and the repository derivable. A few principles underpin it:
• Derive, don't maintain. Dates come from git, and overview pages are generated from frontmatter. Don't hand-maintain things that can be derived.
• Editor-agnostic. Plain markdown with relative links. Nothing should rely on a specific editor's features.
Adding a note
Before committing a new note, make sure:
• It has frontmatter with at least one kind-object (application, concept, operating-system, format, …) — the kind-object is what gives the note its type. A note may carry several (e.g. a language is both a concept and has a format). See Meta.md.
• It lives in the folder that matches its topic.
• Notes you reference are linked with relative ../path.md links, and notes that reference yours link back to it.
• It is reachable from a relevant collection / overview note.
• You do not add a date field — last-modified is taken from git history.
Changing the schema
If you propose a schema change you are responsible for updating every note affected by it; all notes must still pass validation. Update Meta.md to match.
Validation
Before committing, run through this checklist.
Check
One command covers both schema validation and dead links; CI runs the same before every deploy:
shell
noita check --strict --broken-links
• Schema: every note's frontmatter is validated against schema.json (configured under [[problems.schema]] in .noita/config.toml).
• Dead links: Markdown links resolve relative to the note, so link with the real path (../../dev/Git.md), not just the file name.
noita unresolved and noita orphans list broken links and notes nothing links to.
Formatting
Keep notes cleanly formatted. jsaw fmt can normalise structured data files, and most editors can format markdown on save.