markz

Docs

The writing that spans the code. It covers how to use markz, the language it reads, and how it is built. What markz is for is on the home page. The docs read best in this order.

  1. Usage: install, render, check a document, and what to tell your agents.
  2. Syntax: the language at a glance, then construct by construct.
  3. Reference: every export, and the tree it works on.
  4. Grammar: the same language, with every exact rule.
  5. Design: how it is built, and what it leaves out.
  6. Quality: what it is held to, and how to read the report.
  7. Plan: what's done and what's next.
  8. Lessons: what building it taught.
  9. Development: build, test, release and deploy the site.

Docs

  • design.md

    How markz is built: the tree it produces, how offsets map to the source, how the parser reads in one pass, and what html() writes and what it refuses. How it is tested is in Quality. Syntax is the language this reads, and the home page says what markz is for.

  • development.md

    How to work on markz itself: build it, test it, release it and deploy its site. The rules for changing it, including the prose rules it follows, are in AGENTS.md.

  • grammar.md

    What markz reads, stated: every construct of syntax.md, by its id, with its productions and the side rules they can't state. syntax.md explains the dialect and this page states it. The tests read it with markz itself, hold markz to it at every construct's edges, and generate documents from it.

  • lessons.md

    What building markz taught, and what could still be better. The build itself is in git history. This keeps what should shape the next change.

  • plan.md

    Where markz is and what comes next. Finished work gets a line or two. The detail lives in the release notes, the code's @prose, the tests and lessons.

  • quality.md

    What markz is held to, and how to read the results. The Quality report shows them for the latest commit on main, measured when the site is built. pnpm quality writes the same report for your working tree.

  • reference.md

    Everything @amitkaps/markz exports: six functions, the read-only Document they work on, and the types of what it holds. None of them takes options. What to do with them is in Usage, and why they are shaped this way is in Design.

  • syntax.md

    The markz language. It is the Markdown people already write, plus {…} for attributes and elements, a metadata block, math and ${…} expressions. There is one way to write each thing. Anything markz doesn't read stays literal text, with a warning that says what to write instead.

  • usage.md

    Install markz, render a document, find out what it rejected, and use what it knows about the document. Each section is a short recipe, and every function it uses is in Reference. The language itself is in Syntax.