IF Commons GitHub

Documentation generator

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

FactValue
Version0.3.7
Conformance levelL1
Distributedgithub, npm
LicensePolyForm-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

NumberSpecificationRequirements
0001Docs31

Folders

FolderWhat it isMay 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.mjsThe 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

CommandWhat it does
bun install --frozen-lockfileInstalls TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them.
bun run verifyRuns the compiler, the specification and trace checks, the tests, check on commons, and the packing of the package.
bun run siteWrites the site into _site at the root of the checkout.
bun run site:checkBuilds the site in a temporary folder and reports every finding; writes nothing in the checkout.
bun run packBuilds, 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

Titles, headings, exports, tables, columns and requirements. Esc closes.