From 17c1aede391674d5cd2693850f4b827abfd0977d Mon Sep 17 00:00:00 2001 From: Kirill Mokevnin Date: Sat, 21 Nov 2026 08:59:19 -0500 Subject: [PATCH 1/2] feat: migrate the site from Honkit to VitePress Build the book with VitePress 2 (alpha) instead of Honkit: - sidebar generated from each locale's SUMMARY.md; SUMMARY.md also renders as a table-of-contents page, fixing the links that 404'd - Honkit-compatible heading ids and the same .html URLs - Mermaid rendered at build time to light/dark SVG images - SEO head tags via transformHead and the built-in sitemap - built-in local search per locale; PDF output dropped Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pages.yml | 2 +- .gitignore | 1 + .oxfmtrc.json | 1 + .syncpackrc.json | 2 +- AGENTS.md | 22 +- CONTRIBUTING.md | 10 +- README.md | 23 +- book/.vitepress/config.mjs | 233 ++ book/.vitepress/mermaid.mjs | 210 ++ .../.vitepress}/og-card.html | 2 +- book/.vitepress/seo.mjs | 217 ++ book/.vitepress/summary.mjs | 82 + book/.vitepress/theme/index.mjs | 7 + book/.vitepress/theme/style.css | 20 + book/LANGS.md | 5 - book/book.json | 64 - book/en/styles/website.css | 11 - book/es/styles/website.css | 11 - book/ru/styles/website.css | 11 - hk.pkl | 9 +- mise.toml | 8 +- package.json | 21 +- patches/@honkit__honkit-plugin-lunr.patch | 13 - .../honkit-plugin-mermaid/assets/mermaid.css | 19 - plugins/honkit-plugin-mermaid/index.js | 159 -- plugins/honkit-plugin-mermaid/package.json | 15 - plugins/honkit-plugin-seo/index.js | 318 --- plugins/honkit-plugin-seo/package.json | 13 - pnpm-lock.yaml | 2518 +++++++---------- pnpm-workspace.yaml | 18 +- tests/search.test.js | 82 - tests/seo.test.mjs | 69 + tests/summary.test.mjs | 61 + 33 files changed, 2038 insertions(+), 2219 deletions(-) create mode 100644 book/.vitepress/config.mjs create mode 100644 book/.vitepress/mermaid.mjs rename {plugins/honkit-plugin-seo => book/.vitepress}/og-card.html (94%) create mode 100644 book/.vitepress/seo.mjs create mode 100644 book/.vitepress/summary.mjs create mode 100644 book/.vitepress/theme/index.mjs create mode 100644 book/.vitepress/theme/style.css delete mode 100644 book/LANGS.md delete mode 100644 book/book.json delete mode 100644 book/en/styles/website.css delete mode 100644 book/es/styles/website.css delete mode 100644 book/ru/styles/website.css delete mode 100644 patches/@honkit__honkit-plugin-lunr.patch delete mode 100644 plugins/honkit-plugin-mermaid/assets/mermaid.css delete mode 100644 plugins/honkit-plugin-mermaid/index.js delete mode 100644 plugins/honkit-plugin-mermaid/package.json delete mode 100644 plugins/honkit-plugin-seo/index.js delete mode 100644 plugins/honkit-plugin-seo/package.json delete mode 100644 tests/search.test.js create mode 100644 tests/seo.test.mjs create mode 100644 tests/summary.test.mjs diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index ddcf85f..a59fb67 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -26,7 +26,7 @@ jobs: version: 2026.11.8 install_args: --locked - run: pnpm install --frozen-lockfile - # Mermaid diagrams are rendered at build time in headless Chromium. + # Mermaid diagrams are rendered to SVG at build time in headless Chromium. - run: pnpm exec playwright install --with-deps chromium - run: mise run build - if: github.event_name != 'pull_request' diff --git a/.gitignore b/.gitignore index 424073a..95ddd81 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ npm-cache/ node_modules/ dist/ +book/.vitepress/cache/ *.pdf *.epub .DS_Store diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 563016f..2832e22 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -6,6 +6,7 @@ ".agents/skills/**", ".claude/skills/**", "dist/**", + "book/.vitepress/cache/**", "pnpm-lock.yaml", "skills-lock.json" ] diff --git a/.syncpackrc.json b/.syncpackrc.json index 273f1bd..2659c08 100644 --- a/.syncpackrc.json +++ b/.syncpackrc.json @@ -1,6 +1,6 @@ { "$schema": "https://syncpack.dev/schema.json", - "source": ["package.json", "plugins/*/package.json"], + "source": ["package.json"], "semverGroups": [ { "dependencies": ["**"], diff --git a/AGENTS.md b/AGENTS.md index 0c6b3a7..08e2100 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,21 +11,21 @@ Operating guide for agents (and humans) working in this repository. ## Diagrams - Diagrams are written as ```` ```mermaid ```` fences directly in the chapter, so the labels are translated together with the prose and GitHub renders them in the repo. -- `plugins/honkit-plugin-mermaid` renders the fences into inline SVG at build time (Mermaid in headless Playwright), so diagrams also survive `honkit pdf`, which never runs JS. +- `book/.vitepress/mermaid.mjs` renders the fences to SVG at build time (Mermaid in headless Playwright), so readers need no JavaScript for them. Each diagram becomes an `` of an SVG file, not inline markup: Vue strips the `\n` - ); - fs.writeFileSync( - path.join(root, locale, 'SUMMARY.md'), - `# Summary\n\n* [${title}](README.md)\n` - ); - } - - execFileSync( - process.execPath, - [require.resolve('honkit/bin/honkit.js'), 'build', root, output], - { - timeout: 30_000, - stdio: 'pipe' - } - ); - - for (const [locale, { title, token }] of Object.entries(editions)) { - const { store, index } = JSON.parse( - fs.readFileSync(path.join(output, locale, 'search_index.json'), 'utf8') - ); - const documents = Object.values(store); - assert.equal(documents.length, 1, `${locale}: unexpected search documents`); - assert.equal(documents[0].title, title, `${locale}: wrong search result title`); - assert.match(documents[0].body, new RegExp(token), `${locale}: wrong search excerpt`); - assert.doesNotMatch( - documents[0].body, - /invisiblestyle/, - `${locale}: styles are not searchable prose` - ); - // Check the actual search index too: correcting the display store alone - // would still let words from another edition match the current page. - const search = lunr.Index.load(index); - assert.equal(search.search(token).length, 1, `${locale}: local word must match`); - assert.equal(search.search('invisiblestyle').length, 0, `${locale}: CSS must not match`); - for (const other of Object.values(editions).filter((edition) => edition.token !== token)) { - assert.equal( - search.search(other.token).length, - 0, - `${locale}: foreign word must not match` - ); - } - } - } finally { - fs.rmSync(root, { recursive: true, force: true }); - } -}); diff --git a/tests/seo.test.mjs b/tests/seo.test.mjs new file mode 100644 index 0000000..4c434c8 --- /dev/null +++ b/tests/seo.test.mjs @@ -0,0 +1,69 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; + +import { createSeo, describe, truncate } from '../book/.vitepress/seo.mjs'; + +/** @param {string} body */ +const page = (body) => `
${body}
`; + +test('the description is the first paragraph of the preferred section', () => { + const html = page( + '

Title

Lead.

' + + '

Problem

The problem.

' + + '

Intent

A note.

The intent.

' + ); + assert.equal(describe(html, ['intent', 'problem']), 'The intent.'); + assert.equal(describe(html, ['propósito', 'problem']), 'The problem.'); +}); + +test('without a listed section the description skips an all-italic note', () => { + const html = page('

Tool

Checked on 2026-11-01.

What it is.

'); + assert.equal(describe(html, ['intent']), 'What it is.'); +}); + +test('a long description is cut on a word boundary', () => { + const text = `${'word '.repeat(40)}end`; + const result = truncate(text); + assert.ok(result.length <= 160, String(result.length)); + assert.match(result, /word…$/); +}); + +test('head tags carry canonical, hreflang and x-default links', () => { + const seo = createSeo({ + baseUrl: 'https://example.org/book/', + siteName: 'Book', + siteDescription: 'About the book', + locales: ['ru', 'en', 'es'], + defaultLocale: 'en', + image: 'assets/og/{locale}.png', + imageWidth: 1200, + imageHeight: 630, + descriptionSections: ['назначение'] + }); + const siteConfig = /** @type {any} */ ({ + pages: ['ru/grilling.md', 'en/grilling.md', 'ru/README.md'], + rewrites: { map: { 'ru/README.md': 'ru/index.md' } } + }); + const head = seo.transformHead( + /** @type {any} */ ({ + page: 'ru/grilling.md', + siteConfig, + pageData: { title: 'Гриллинг' }, + content: page('

Гриллинг

Назначение

Суть.

') + }) + ); + const find = (/** @type {Record} */ attributes) => + head.find(([, attrs]) => + Object.entries(attributes).every(([key, value]) => attrs[key] === value) + )?.[1]; + + assert.equal(find({ name: 'description' })?.content, 'Суть.'); + assert.equal(find({ rel: 'canonical' })?.href, 'https://example.org/book/ru/grilling.html'); + assert.equal(find({ hreflang: 'en' })?.href, 'https://example.org/book/en/grilling.html'); + assert.equal(find({ hreflang: 'x-default' })?.href, 'https://example.org/book/en/grilling.html'); + assert.equal(find({ hreflang: 'es' }), undefined); + assert.equal( + find({ property: 'og:image' })?.content, + 'https://example.org/book/assets/og/ru.png' + ); +}); diff --git a/tests/summary.test.mjs b/tests/summary.test.mjs new file mode 100644 index 0000000..b453bdc --- /dev/null +++ b/tests/summary.test.mjs @@ -0,0 +1,61 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import { test } from 'node:test'; + +import { parseSummary, readSummary } from '../book/.vitepress/summary.mjs'; + +test('SUMMARY.md becomes top-level links, groups and nested groups', () => { + const source = [ + '# Contents', + '', + '* [Introduction](README.md)', + '* [Preface](preface.md)', + '', + '## Spec-driven development', + '', + '* [Overview](spec-driven-development.md)', + '', + '### Tool reviews', + '', + '* [OpenSpec](openspec.md)', + '', + '## Anti-patterns', + '', + '* [Vibe coding](vibe-coding.md)', + '' + ].join('\n'); + + assert.deepEqual(parseSummary(source, 'en'), [ + { text: 'Introduction', link: '/en/' }, + { text: 'Preface', link: '/en/preface' }, + { + text: 'Spec-driven development', + items: [ + { text: 'Overview', link: '/en/spec-driven-development' }, + { text: 'Tool reviews', items: [{ text: 'OpenSpec', link: '/en/openspec' }] } + ] + }, + { text: 'Anti-patterns', items: [{ text: 'Vibe coding', link: '/en/vibe-coding' }] } + ]); +}); + +test('a nested group before any group is an error', () => { + assert.throws(() => parseSummary('### Orphan\n', 'en'), /before any "##"/); +}); + +test('every chapter in each SUMMARY.md exists in its locale', () => { + for (const locale of ['ru', 'en', 'es']) { + const links = readSummary(`book/${locale}/SUMMARY.md`, locale) + .flatMap(function flatten(item) { + return [item, ...(item.items ?? []).flatMap(flatten)]; + }) + .map((item) => item.link) + .filter((link) => link !== undefined); + + assert.ok(links.length > 0, locale); + for (const link of links) { + const page = link.slice(`/${locale}/`.length) || 'README'; + assert.ok(fs.existsSync(`book/${locale}/${page}.md`), `${locale}: ${link}`); + } + } +}); From 982f612f8c5bc88774dc3cc1be1da038114e1591 Mon Sep 17 00:00:00 2001 From: Kirill Mokevnin Date: Sat, 21 Nov 2026 09:17:55 -0500 Subject: [PATCH 2/2] feat: render diagrams with vitepress-mermaid Replace the build-time Playwright renderer, which hung the CI build, with mokevnin/vitepress-mermaid: diagrams are drawn in the browser and redrawn on a theme toggle. The book palette and its dark variant are passed as getters, so each render picks the palette for the current mode. Playwright and mermaid-isomorphic are no longer dependencies. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pages.yml | 2 - AGENTS.md | 6 +- CONTRIBUTING.md | 2 +- README.md | 2 +- book/.vitepress/config.mjs | 16 +- book/.vitepress/mermaid.mjs | 210 ---------------------- book/.vitepress/og-card.html | 2 +- book/.vitepress/theme/index.mjs | 12 +- book/.vitepress/theme/mermaid-palette.mjs | 56 ++++++ book/.vitepress/theme/style.css | 20 +-- package.json | 4 +- pnpm-lock.yaml | 82 +++------ pnpm-workspace.yaml | 12 +- 13 files changed, 101 insertions(+), 325 deletions(-) delete mode 100644 book/.vitepress/mermaid.mjs create mode 100644 book/.vitepress/theme/mermaid-palette.mjs diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index a59fb67..5becde7 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -26,8 +26,6 @@ jobs: version: 2026.11.8 install_args: --locked - run: pnpm install --frozen-lockfile - # Mermaid diagrams are rendered to SVG at build time in headless Chromium. - - run: pnpm exec playwright install --with-deps chromium - run: mise run build - if: github.event_name != 'pull_request' uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 diff --git a/AGENTS.md b/AGENTS.md index 08e2100..36437bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,10 +11,9 @@ Operating guide for agents (and humans) working in this repository. ## Diagrams - Diagrams are written as ```` ```mermaid ```` fences directly in the chapter, so the labels are translated together with the prose and GitHub renders them in the repo. -- `book/.vitepress/mermaid.mjs` renders the fences to SVG at build time (Mermaid in headless Playwright), so readers need no JavaScript for them. Each diagram becomes an `` of an SVG file, not inline markup: Vue strips the `