Šķîþ ţö ḿàîñ çöñţéñţ

Ļéàŕñ ķàþî › Start here: your writing

A project and its files

What kapi reads, and how it addresses every piece of content.

A kapi project is a recipe beside the files it governs. This lab opens the Northsea repository, reads its recipe, lists the files kapi claims, and looks at how the engine turns a Markdown page and a JSON catalog into the same thing: blocks, each with an address.

  1. A company repositorylsNorthsea Maritime Systems keeps its operator documentation, the strings of its Compass interface and one marketing page in one repository, in one language. The recipe at the root, kapi.yaml, says which of these files are content.
  2. The recipecat kapi.yamlThree collections name files by pattern and bind each to a point: northsea/docs, northsea/app and northsea/landing. The API reference and the changelog sit inside the documentation collection and take a point of their own, because a published record reads differently from a procedure.
  3. The files kapi readskapi lskapi ls is the recipe applied to the tree: every file a collection claims, with the format it is read in. A file no pattern matches is not content.
  4. Measure a filekapi stats docs/berths.mdMeasure before anything is changed or translated. A block is one piece of content: a paragraph, a heading, a list item. Segments are the sentences inside the blocks.
  5. Every block has an addresskapi inspect docs/berths.md | head -40kapi inspect prints the blocks the reader found. Each carries a ref, the document and the block's place in it, and a rev, the revision of its text. Every later verb, from a check finding to an edit, names content this way.
  6. Keyed formatskapi inspect app/strings.en.json | head -24In a catalog the key is the block's name: nav.plan, plan.title. The same model holds a Markdown paragraph and a JSON string, so one check, one edit and one translation step serve both.
  7. Every format, one modelkapi formatsThe reader for each format parses into this model, and its writer puts the content back around the text that changed, byte for byte. The list is the engine's own: what it reads, what it writes, and how faithfully.