Yap

Yet Another Proposals — short documents that freeze cross-project intents (conventions, defaults, preferences) in YAMD.

Background

Ideas worth carrying between projects — "use TOML for human config", "log this way", "write titles in Title Case" — otherwise live only in my head and drift. A YAP is a PEP/RFC-style note that pins one such intent to a number, so it can be referenced and reused. The number freezes the intent; the prose behind it may be revised freely afterwards. See yap/yap-002.yamd for the format itself.

Install

Requires Nix with flakes. The yamd renderer is pulled in as a flake input and wrapped so the project-local yap plugin resolves:

nix develop        # yamd on PATH, git hooks installed

Usage

Layout:

yap/
	000-template.yamd   ← copy this to start a new YAP
	NNN-slug.yamd       ← a numbered proposal (addressed as yap-NNN in prose)
	_index.yamd         ← toctree + glossary over the whole set
drafts/
	_next-number.txt    ← counter for independent, not-yet-numbered drafts
support/yamd-lib/yap/  ← the `yap` YAMD plugin (header + version + keywords + #ref-yap)

Start a new YAP by copying the template and giving it the next free number:

cp yap/000-template.yamd yap/006-my-idea.yamd

Render one to HTML:

nix run . -- yap/002-yap-format.yamd -o out.html

Or build the whole set — single inlines every YAP into one page, multi writes one page per document:

nix run . -- yap/_index.yamd -o out.html            # combined
nix run . -- --mode multi yap/_index.yamd -o site/  # one page per YAP

Format all YAP sources in place (also run as a pre-commit hook):

nix run . -- --fmt yap/*.yamd

Contributing

I am the only author. Commit and workflow notes: docs/contributing/README.md.

License

GPL-3.0 © 2026 kp2pml30