Compile API
| Export | Purpose |
|---|---|
compileGuides, compileGuideResults |
Stitch shards into compiled guide text |
compileGuideResultsWithContext |
The results of compileGuideResults, with the guide link index, the shard cache it built and the shards each guide compiles, its manifest’s and those the linked-shard walk finds (linkedFilesByGuide) |
compileGuidesFromResults |
What compileGuides returns, from results already compiled |
writeCompiledGuides, writeCompiledGuidesFromResults |
Write compiled guides and the optional monolith to disk, the second from results already compiled |
compiledOutputDocuments |
Each file compile writes, with the text written there |
buildGuideLinkIndex |
The guide link index alone, with the shard cache it filled |
createShardCache, loadShardSnapshot |
A cache of shard reads that compile and link lint can share |
writeOutputFile, resolveBackupPath |
Opt-in backup before overwrite; backup path resolver |
resolveBackupOptions |
Merge config and CLI backup settings |
WriteOutputBackupOptions |
Backup options type |
sectionFiles, processSection, assembleGuide |
Lower-level assemble pipeline |
formatCompileTitle, extractFirstHeading, … |
Optional compile.title injection and deduplication |
demoteHeadings, stripAboutThisGuideHeading, … |
Heading transforms |
rewriteCrossGuideFileLinks, rewriteIntraGuideFileLinks, slugForSectionFile |
Two of the link passes, and the slug of a shard’s demoted first heading, before guide numbering |
stripExplicitAnchorMarkers |
The stripAnchors transform on a string |
registerCompileHook, applyCompileHooks |
Extension hooks (stripAnchors, inlineInserts, …) |
compileGuideResults returns one result per guide. Its text is the guide’s compiled guide, with links and source tags relative to that file. The monolith is the one file that top-level outputFile names, and it stitches each guide without compile.outputFile. A guide in the monolith also has a copy there, and its result stores that copy in monolithText, with paths and section slugs as the monolith has them.
A result’s knownSlugs holds the section slugs of text, the slug of each section it stitches, such as a FIND-* finding id or a declared {#id}. monolithKnownSlugs does the same for monolithText: the section slugs of every copy in the monolith, a set each copy shares. Broken-link marking and lintLinks accept a #fragment that matches one of these slugs or a heading, as BROKEN LINK marker says. A fragment on a link from another output has to match a heading there, so neither set counts for it, as Validation phases says.
compiledOutputDocuments(results, options) returns each file that compile writes from the same results and options: every compiled guide in compileOrder, then the monolith when the config sets top-level outputFile and at least one guide is stitched into it. The monolith’s path is the config’s outputFile under outputDir, the path that resolveOutputPath gives and the CLI passes to writeCompiledGuidesFromResults. Each entry has the absolute path and the text written there, banner included, so a line number in the text is a line of the file. A compiled guide’s entry names its result in guide. The monolith’s entry lists each guide’s copy in copies, with the line the copy starts on. lintLinks reads the outputs through it, and so does refsOutputTexts, which gives the refs registry each output’s text.
When top-level outputFile is set, compileGuides returns the monolith text, which leaves out guides with compile.outputFile. Otherwise it returns every compiled guide joined in the order of compileOrder. compileGuidesFromResults does the same from results, and it stitches the monolith from each result’s monolithText. writeCompiledGuides writes each compiled guide to its output path. It also writes the monolith when you pass its path and at least one guide has no compile.outputFile.
writeOutputFile writes compile targets. Default: overwrite. When backup.enabled is true, it moves an existing file to the path that Backup path layout gives before writing. Pass backup on CompileOptions or resolve via resolveBackupOptions(config, cliOverrides).
When compile.title is set, assembleGuide injects a ## heading followed by a blank line before the first section. Feature settings in Config reference says which spec covers each feature’s config keys, backup included.
Locale packs
Section titled “Locale packs”A locale pack holds the words compile writes and reads in prose, such as the BROKEN LINK marker and the line-range words of codeEvidence. Compile and lintLinks use the en-US pack, the only one getLocalePack resolves. buildSlugRegistry and stripAboutThisGuideHeading take a pack as an argument, and markBrokenLinks and lintCompiledLinks take one as their locale option. Each uses en-US without one.
| Export | Purpose |
|---|---|
getLocalePack(id), listLocalePackIds, DEFAULT_LOCALE_ID, enUS |
Resolve a built-in pack by its BCP 47 id, en-US by default |
createLocalePack(options), createBrokenLinksCopy, createInsertsCopy, formatTemplate |
Build a pack from message templates |