From 0f725580334f3ae94d7210f6fd87d5d44c9ea387 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 28 May 2026 20:51:31 +0200 Subject: [PATCH 1/4] Remove unused Rouge CSS. --- docs/assets/css/rouge.css | 116 -------------------------------------- 1 file changed, 116 deletions(-) delete mode 100644 docs/assets/css/rouge.css diff --git a/docs/assets/css/rouge.css b/docs/assets/css/rouge.css deleted file mode 100644 index dfebb54b..00000000 --- a/docs/assets/css/rouge.css +++ /dev/null @@ -1,116 +0,0 @@ -.highlight table td { padding: 5px; } -.highlight table pre { margin: 0; } -.highlight, .highlight .w { - color: #24292f; - background-color: #f6f8fa; -} -.highlight .k, .highlight .kd, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kt, .highlight .kv { - color: #cf222e; -} -.highlight .gr { - color: #f6f8fa; -} -.highlight .gd { - color: #82071e; - background-color: #ffebe9; -} -.highlight .nb { - color: #953800; -} -.highlight .nc { - color: #953800; -} -.highlight .no { - color: #953800; -} -.highlight .nn { - color: #953800; -} -.highlight .sr { - color: #116329; -} -.highlight .na { - color: #116329; -} -.highlight .nt { - color: #116329; -} -.highlight .gi { - color: #116329; - background-color: #dafbe1; -} -.highlight .ges { - font-weight: bold; - font-style: italic; -} -.highlight .kc { - color: #0550ae; -} -.highlight .l, .highlight .ld, .highlight .m, .highlight .mb, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mx { - color: #0550ae; -} -.highlight .sb { - color: #0550ae; -} -.highlight .bp { - color: #0550ae; -} -.highlight .ne { - color: #0550ae; -} -.highlight .nl { - color: #0550ae; -} -.highlight .py { - color: #0550ae; -} -.highlight .nv, .highlight .vc, .highlight .vg, .highlight .vi, .highlight .vm { - color: #0550ae; -} -.highlight .o, .highlight .ow { - color: #0550ae; -} -.highlight .gh { - color: #0550ae; - font-weight: bold; -} -.highlight .gu { - color: #0550ae; - font-weight: bold; -} -.highlight .s, .highlight .sa, .highlight .sc, .highlight .dl, .highlight .sd, .highlight .s2, .highlight .se, .highlight .sh, .highlight .sx, .highlight .s1, .highlight .ss { - color: #0a3069; -} -.highlight .nd { - color: #8250df; -} -.highlight .nf, .highlight .fm { - color: #8250df; -} -.highlight .err { - color: #f6f8fa; - background-color: #82071e; -} -.highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cp, .highlight .cpf, .highlight .c1, .highlight .cs { - color: #6e7781; -} -.highlight .gl { - color: #6e7781; -} -.highlight .gt { - color: #6e7781; -} -.highlight .ni { - color: #24292f; -} -.highlight .si { - color: #24292f; -} -.highlight .ge { - color: #24292f; - font-style: italic; -} -.highlight .gs { - color: #24292f; - font-weight: bold; -} From 87ffed7808a57b7253ce7d3564a5b37797ae1d59 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Wed, 27 May 2026 23:36:52 +0200 Subject: [PATCH 2/4] This is a tB document, no need to restate it. --- docs/Miscellaneous/FAQs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Miscellaneous/FAQs.md b/docs/Miscellaneous/FAQs.md index 6bbe8c93..6afd477a 100644 --- a/docs/Miscellaneous/FAQs.md +++ b/docs/Miscellaneous/FAQs.md @@ -4,7 +4,7 @@ nav_order: 2 permalink: /FAQ --- -# twinBASIC Frequently Asked Questions +# Frequently Asked Questions ### [General](#general) - [Installation](#install-section) - [Using twinBASIC](#using-twinbasic) From ca502c6a3075af84184cf8e5a0f808f5c16ebe3f Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Wed, 27 May 2026 23:37:46 +0200 Subject: [PATCH 3/4] Make it clear that book.yml is used by tbdocs and not by the PDF renderer. --- docs/Documentation/Builder.md | 2 ++ docs/Documentation/Tools.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Documentation/Builder.md b/docs/Documentation/Builder.md index 2602cc84..1d325013 100644 --- a/docs/Documentation/Builder.md +++ b/docs/Documentation/Builder.md @@ -147,6 +147,8 @@ The largest module by line count (~990 lines), split into two clearly-labelled h 4. shift heading levels by `n in [0, 3]` capped at `h7-stub`; 5. prefix every heading id and intra-chapter `href="#"` with the chapter anchor. +Each part and chapter divider page carries the entry's title as an H1/H2 heading (or a silent `

` when `no_outline_entry:` is set), which becomes the PDF bookmark target. When `landing_is_target:` is set on an entry, the heading is instead injected directly into the landing-page article so the PDF bookmark navigates there rather than to the blank divider page; `rewriteBookHrefs`'s landing-H1 strip skips the injected heading via a `data-divider-heading` attribute. `outline_closed:` stamps `data-pdf-bookmark-closed` on the heading (or on the first content article for `no_outline_entry` entries), and `parseOutline` in `docs/lib/outline.mjs` reads the attribute to write a negative PDF `/Count` for that bookmark node. Full schema is documented in the `_data/book.yml` file header. + `augmentWithRedirectStubs` synthesises virtual `Page` records from each real page's `redirect_from` so the cross-ref rewriter still captures legacy URLs the way Jekyll's `jekyll-redirect-from` did (its stubs landed in `site.pages` and got swept into the lookup table). `chapterAnchorFromUrl` is the URL → `ch-…` slug helper that drives both `id="..."` and the `#…` href targets. ### [build-info.mjs](https://github.com/twinbasic/documentation/blob/main/builder/build-info.mjs) --- Phase 2 git capture diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md index 0a747e6b..1e84d0f4 100644 --- a/docs/Documentation/Tools.md +++ b/docs/Documentation/Tools.md @@ -111,7 +111,7 @@ Normalises literal en-dash / em-dash characters in markdown source under `docs/` node docs/render-book.mjs -o [options] -The PDF renderer that `book.bat` calls. Drives `puppeteer` + `paged.js` + `pdf-lib` directly, so it controls `pdf-lib`'s `parseSpeed` (the default yields the event loop between every 100 objects on load, adding ~32 seconds to a 100-second build for no reason in Node --- see [perf/README.md](https://github.com/twinbasic/documentation/blob/main/perf/README.md) for the diagnosis). Replaces an earlier `npx pagedjs-cli ...` invocation. +The PDF renderer that `book.bat` calls. It is a generic HTML-to-PDF converter: it takes the pre-built `_site-pdf/book.html` as its sole document input and has no knowledge of `_data/book.yml` --- all chapter structure, heading levels, and outline entries are already embedded in the HTML by `tbdocs` Phase 8. Drives `puppeteer` + `paged.js` + `pdf-lib` directly, so it controls `pdf-lib`'s `parseSpeed` (the default yields the event loop between every 100 objects on load, adding ~32 seconds to a 100-second build for no reason in Node --- see [perf/README.md](https://github.com/twinbasic/documentation/blob/main/perf/README.md) for the diagnosis). Replaces an earlier `npx pagedjs-cli ...` invocation. Key options used by `book.bat`: @@ -128,6 +128,6 @@ The build pipeline also reads a handful of declarative files. They are not execu | File | Effect | |---|---| | `docs/_config.yml` | Site config. `tbdocs` reads `url`, `baseurl`, `title`, `logo`, `also_build_offline`, `also_build_pdf`, `offline_exclude`, `enable_copy_code_button`, the footer / aux-link knobs, the GitHub edit-link knobs, and the offline-download-link knobs. Jekyll-only keys (`markdown`, `kramdown`, `theme`, `highlighter`, the `defaults` block, the `compress_html` block, the `exclude` list) are ignored. | -| `docs/_data/book.yml` | The PDF book's table of contents. Each entry resolves to one or more pages via `page` / `pages` / `nav_page` / `nav_pages` selectors plus an optional `no_descent` flag. `tbdocs`'s [`book.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/book.mjs) iterates over every entry and stores the resolved chapter array as `entry._chapters` for the renderer pass. | +| `docs/_data/book.yml` | The PDF book's chapter manifest. Entries are resolved to pages via the selector schema (`page` / `pages` / `nav_page` / `nav_pages` / `no_descent`) and control PDF outline behaviour via `landing_page:`, `landing_is_target:`, `no_outline_entry:`, `no_heading_shift:`, and `outline_closed:`. Full schema is documented in the file header. Phase 2 resolves chapter arrays; Phase 8 assembles `book.html`. | | `builder/themes/Light.theme`, `Dark.theme`, `Classic.theme` | twinBASIC IDE theme files, vendored from the BETA installer. `builder/highlight-theme.mjs` parses them into a Symbol-keyed palette that drives both the renderer's scope-to-class mapping and the generated `tb-highlight.css`. Refresh from the installer when the IDE adds new palette entries. | | `builder/twinbasic.tmLanguage.json` | TextMate grammar for the twinBASIC language. Shiki uses it to tokenise every ` ```tb ` code block. | From db4e3b07c55d9a83f6025c30b5843e669d619653 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Thu, 28 May 2026 20:52:26 +0200 Subject: [PATCH 4/4] Make the code blocks more readable by growing their font size. --- builder/assets/css/just-the-docs-combined.css | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/builder/assets/css/just-the-docs-combined.css b/builder/assets/css/just-the-docs-combined.css index 82c2a58a..ee603dac 100644 --- a/builder/assets/css/just-the-docs-combined.css +++ b/builder/assets/css/just-the-docs-combined.css @@ -264,7 +264,7 @@ a:not([class]) { text-decoration: underline; text-decoration-color: #eeebee; tex a:not([class]):hover { text-decoration-color: rgba(114, 83, 237, 0.45); } -code { font-family: "SFMono-Regular", menlo, consolas, monospace; font-size: 0.75em; line-height: 1.4; } +code { font-family: "SFMono-Regular", menlo, consolas, monospace; font-size: 0.95em; line-height: 1.4; } figure, pre { margin: 0; } @@ -760,7 +760,7 @@ tbody tr:last-of-type td { padding-bottom: 0.75rem; } thead th { border-bottom: 1px solid #eeebee; } -:not(pre, figure) > code { padding: 0.2em 0.15em; font-weight: 400; background-color: #f5f6fa; border: 1px solid #eeebee; border-radius: 4px; } +:not(pre, figure) > code { padding: 0.15em 0.12em; font-weight: 400; background-color: #f5f6fa; border: 1px solid #eeebee; border-radius: 4px; } a:visited code { border-color: #eeebee; } @@ -2073,7 +2073,7 @@ html.dark-mode a:not([class]) { text-decoration: underline; text-decoration-colo html.dark-mode a:not([class]):hover { text-decoration-color: rgba(44, 132, 250, 0.45); } -html.dark-mode code { font-family: "SFMono-Regular", menlo, consolas, monospace; font-size: 0.75em; line-height: 1.4; } +html.dark-mode code { font-family: "SFMono-Regular", menlo, consolas, monospace; font-size: 0.95em; line-height: 1.4; } html.dark-mode figure, html.dark-mode pre { margin: 0; } @@ -2569,7 +2569,7 @@ html.dark-mode tbody tr:last-of-type td { padding-bottom: 0.75rem; } html.dark-mode thead th { border-bottom: 1px solid #44434d; } -html.dark-mode :not(pre, figure) > code { padding: 0.2em 0.15em; font-weight: 400; background-color: #31343f; border: 1px solid #44434d; border-radius: 4px; } +html.dark-mode :not(pre, figure) > code { padding: 0.15em 0.12em; font-weight: 400; background-color: #31343f; border: 1px solid #44434d; border-radius: 4px; } html.dark-mode a:visited code { border-color: #44434d; } @@ -3555,4 +3555,6 @@ html.dark-mode .site-footer { color: #959396; } html.dark-mode h1, html.dark-mode h2, html.dark-mode h3, html.dark-mode h4, html.dark-mode h5, html.dark-mode h6, html.dark-mode #toctitle { font-weight: 500; } +td code, th code { font-size: 1em; } + /*# sourceMappingURL=just-the-docs-combined.css.map */ \ No newline at end of file