Library
A library is a folder holding afolio.yamlcharter, acontent/folder of linked documents, anassets/folder, and the generated indices in.folio/. It can be a project'sdocs/folder, a notes folder, or a whole repository.
Everything folio does is scoped to one library. The folder on the right is the whole of one. Every document is under content/, one folder per genre; nothing outside it is a document.
Pick a writer to see which folders it owns. No folder has two.
- folio.yamlThe charter: name, purpose, reader, voice, packs, home maps, check severities.
- content/Every document, one folder per genre, the journal included.
- index.htmlThe home page, the map named
home. - concepts/<slug>/A concept, with its files beside it.
- journal/<yyyy>/One Markdown file per entry.
- maps/, notes/, …Each other genre's folder, as its card names it.
- assets/What documents cite but are not documents.
- figures/Figure sources and their rendered files.
- refs.bibThe library's one bibliography.
- data/Datasets that documents cite.
- genres/<name>/This library's overrides, variants and genres of its own.
- workflows/<name>.mdThis library's own workflows.
- packs/<name>/This library's own packs.
- .folio/The generated indices, committed, and checked current by the gate.
- catalog.jsonEvery document's metadata, map rows and topics.
- backlinks.json, search.jsonWhat cites what, and the search index.
- nav.json, journal.json, cards.jsonGuide navigation, the timeline and the flashcards.
- redirects.jsonThe one file here that is state: old addresses, written by moves.
The charter says what the library is. Only the set-up and configure skills write it, and every change is shown as a diff and recorded in the journal.
Documents are written through the skills, and every one goes through write, its genre's card and the gate. Assets are committed with the documents that cite them.
Its own genres, workflows and packs are added and changed by the configure skill. Each is found before a pack's or the core's of the same name.
Generated files are written by folio index and never by hand. redirects.json is written by folio mv, promote and rm.
Where a library sits
A library is wherever a folio.yaml is. One project can hold more than one. When a library sits inside a larger project, the charter's root: names the project root, and a path a document gives to something outside the library, such as a result's evidence, resolves from there.
A project's docs/
The library beside the code it documents. This library is one: folio's own docs/, with root: .. pointing at the repository.
A notes folder
A personal library of concepts, notes and readings, inside whatever repository holds it.
A whole repository
The repository is the library, and its root holds the charter.
One library, one scope
- The gate checks one library.
- The site exports one library.
- Ids are unique within one library, whatever the genre.
- Search covers one library, and a charter can list others to search alongside its own.
What changes it
Every change goes through one of the seven skills, which call the folio command and end at the gate.