The generator of a repository's documentation site, a library of commons that any repository installs from npm (@intellectual-frontiers/docs) and runs as ifc-docs. It reads only the repository's TypeScript (module documentation, TSDoc, the about of each package, examples, and the values of models and programs) and its spec kit, through the TypeScript 7.1 programmatic API and the libraries' own functions, and writes a static site with a Markdown twin and JSON beside it, with no framework: code is coloured and diagrams are drawn when the site is built. A repository says what to read in a typed configuration, docs.config.ts, which imports the types and the lens factories by package name and gives the address and branch of the repository, so that a private repository has a site whose links go where it says. Commons' own is commons/docs.config.ts. Nothing is written for a site alone but its guides.
Specification: commons 0001-docs
| Fact | Value |
|---|
| Version | 0.3.7 |
| Conformance level | L1 |
| Distributed | github, npm |
| License | PolyForm-Noncommercial-1.0.0, source-available: free for noncommercial use, commercial use needs a license from the owner (see Licensing in Start here) |
| Import it as | @intellectual-frontiers/docs |
#Areas
#Imports
Core, Lang Sql, Libraries, System
#Specifications
| Number | Specification | Requirements |
|---|
0001 | Docs | 31 |
#Folders
| Folder | What it is | May import |
|---|
src/ | The generator: the configuration and its one check, the readers of the spec kits and of the API, the page model, the pages, the HTML and Markdown writers, the lenses and the command line. | core and system, by package name; typescript/async; shiki; beautiful-mermaid |
src/extract/ | The readers of the spec kits (both layouts) and of the API, through typescript/async. | src/; typescript/async |
src/emit/ | The page model written as HTML and Markdown, and the search index. | src/; shiki; beautiful-mermaid |
src/lens/ | The factories of the lenses a configuration passes: layered models, programs, guides and releases. | src/mod.ts only |
src/theme/ | The stylesheet and the one script of the site, published beside the modules that read them. | nothing: CSS and a browser script |
ifc-docs.mjs | The command ifc-docs in this repository: it runs the command line from the sources, on Bun and on Node 26 alike; the published package has its own launcher of the compiled module. | the Node hook; src/cli.ts |
tools/ | The trace check and the packer that bun run verify runs. | mizan and the packer of commons, by package name |
suite/ | The tests, with the HTML of the fixtures committed under golden/, a fixture repository under fixture-repo/ and the packed package installed into an empty project. | anything here |
#Commands
| Command | What it does |
|---|
bun install --frozen-lockfile | Installs TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them. |
bun run verify | Runs the compiler, the specification and trace checks, the tests, check on commons, and the packing of the package. |
bun run site | Writes the site into _site at the root of the checkout. |
bun run site:check | Builds the site in a temporary folder and reports every finding; writes nothing in the checkout. |
bun run pack | Builds, inspects and packs the package into dist/. |
IFCDOCS_UPDATE_GOLDEN=1 bun test suite/ | Writes the fixtures' HTML again; then read the diff. |
#Quality
Quality: 109 tests: 100 passed, 9 failed, 0 skipped, 25 of 31 requirements proved, 0 open issues, 0 open tickets. The tests and issues of the library