Documentation Development

This section covers everything related to the twinBASIC documentation: the URL contract the compiler and IDE rely on, how to author a page in the house style, the build / preview / deploy workflow for content contributors, every script and batch file in the repository, and the internals of the tbdocs static site generator that produces the site.

Toolchain overview

Three commands handle the entire build-and-verify workflow for a content change. build.bat produces three output trees from the markdown source and link-checks them in the same pass; check.bat runs the further gates that read those trees, from the freshness check to the accessibility scan; book.bat renders the PDF from the third tree. A fourth wrapper, test.bat, tests the toolchain itself rather than the site, and is needed when a change reaches outside docs/. Tools and Scripts names the gates each one runs, in order.

One more wrapper, examples.bat, sits outside that workflow and outside CI altogether: it compiles the twinBASIC code samples in the pages themselves, which needs a twinBASIC install and Windows — see Checking that a sample compiles.

build.bat must run before check.bat or book.bat — check.bat audits _site-offline/ and refuses a tree older than the sources that produced it, while book.bat reads from _site-pdf/. A clean build.bat && check.bat is the bar for “ready to commit”.

Build pipeline

A single build.bat run executes tbdocs against a shared task DAG, dispatched by a SharedArrayBuffer-based pull scheduler — there is no central dispatcher and no fixed phase sequence; workers and the main thread compete for ready tasks directly. The graph is organised into five sections (Seeds, Spine, Render, Write, Check) that also label the timeline on the Build Info page; the tbdocs Builder page documents the full DAG, the scheduler architecture, and each task’s interface contract.

Sub-pages

  • Permanent Links — the stable /tB/ URL contract under which the IDE help system and external references resolve.
  • Authoring Pages — how to write or edit a page so it matches the rest of the site: frontmatter and permalinks, heading levels, formatting, plain-English prose, attribution, and cross-section links.
  • Building and Deployment — the day-to-day workflow for editing content: requirements, building, serving locally, link checking, Graphviz diagrams, screenshots, and the GitHub Pages deployment.
  • Tools and Scripts — one-line-per-tool reference for every script, batch file, and CLI flag exposed by the documentation toolchain (intended audience: doc contributors).
  • tbdocs Builder — detailed technical documentation for the tbdocs static site generator that lives under builder/. Read this when modifying the build pipeline itself. Sub-pages:
    • Pipeline Stages — complete interface reference: per-task signatures and per-module export tables, plus the scheduler-level concepts (flag bits, task lifecycle, SAB layout).
    • Book Configuration — _book.yml key reference for the PDF chapter manifest.
    • Extending the Builder — tutorial for adding a new pipeline task, markdown-it plugin, render-worker sub-stage, or verification gate.
  • Wisdom — the Discord knowledge harvester: a three-phase tool (export, process, extract) that mines the twinBASIC Discord for actionable technical knowledge and drafts documentation additions for human review.
  • PDF Generation — internals of the PDF renderer: render-book.mjs, paged.browser.js, and the pdf-lib shims.
  • Library Patches — every modification to paged.browser.js and the fast-*.mjs pdf-lib shims: upstream problem, applied fix, and mechanism.