Skip to content

feat: Add multilingual mdBook reading worlds - #4

Merged
tgrospic merged 27 commits into
alux-network:masterfrom
shixi-11:feat/mdbook-reader-handoff
Oct 29, 2026
Merged

tgrospic merged 27 commits into
alux-network:masterfrom
shixi-11:feat/mdbook-reader-handoff

Conversation

@shixi-11

@shixi-11 shixi-11 commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Add eleven language editions with a forest gateway, a paginated magic-book reader and a scrolling documentation reader. The reader includes themes, search, bookmarks, reading-position continuity, language switching and localized sharing metadata. Responsive relayout retains normalized reading progress; aggregate print pages preserve the complete book and the visitor's saved world. Keyboard help follows the selected language.

Use canonical Markdown sources and native mdBook output, with strict TypeScript and Vite for the interface. The two worlds share content and native search indexes. An HTML-only preprocessor normalizes actual image destinations after native admonitions and math, preserving literal code, labels and shared link definitions. Its parser dependencies stay outside the reader bundle. Complete output is staged before replacement, with rollback for failed directory swaps. Development startup waits for the initial book and watches normalized paths on Windows. Site verification includes generated pages, and repeatability covers the mdBook output, reader bundle and public assets.

This consolidates and supersedes #2 and #3, taking over Tomislav's completed npm-ws integration, including the merged follow-up from tgrospic#1 and his latest sidebar, language-menu and toolbar refinements. Existing commits retain their original authorship.

The English README links to ten localized repository introductions matching the website editions. Each introduction uses its language's share card and accurately distinguishes Tomislav Grospić's book, initial website and mdBook architecture work from Shixi Lin's interface and reader contributions. Share-card sources preserve the full Croatian author spelling. Build instructions remain canonical in the English README; root AGENTS.md records handover and localization conventions. Browser automation covers desktop engines and mobile profiles; physical-device acceptance remains outstanding.

tgrospic and others added 20 commits October 28, 2026 15:14
fix(reader): Refine reading continuity and add cross-browser acceptance
Copilot AI balanced review requested due to automatic review settings October 28, 2026 21:00
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-28T21:10:31.158986Z 4ed8cbd PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Publication can destroy the working site and leave partial output on failure, while tests omit required negative cases and full-site build repeatability checks.

5 open issues
What changed in this PR

Adds multilingual reading experiences to the existing mdBook site, consolidating the earlier reader work while keeping canonical Markdown and native mdBook rendering.

Changes:

  • Introduces language selection, source localization, and a Vite/TypeScript build pipeline.
  • Adds translated chapters, shared asset paths, and explicit video clip boundaries.
  • Adds site verification and repeatability tests, and integrates the new toolchain into CI.
File Description
web/​test/​site.test.ts Adds site validation and broken-copy tests.
web/​test/​build.test.ts Compares two clean mdBook builds.
web/​test/​book-json.ts Exports mdBook structure for test expectations.
web/​mdbook.ts Builds and assembles language editions.
web/​localize.ts Selects translations and warns about stale sources.
web/​languages.ts Defines the eleven supported editions.
vite.config.ts Integrates mdBook builds and reader bundling.
tsconfig.json Enables strict TypeScript checking.
theme/​version.js Removes the standalone sidebar-version script.
src/​rust-dd/​capability-algebras.md Uses the shared public image path.
src/​insights/​index.zh.md Adds Simplified Chinese Insights introduction.
src/​insights/​index.zh-hant.md Adds Traditional Chinese Insights introduction.
src/​insights/​index.vi.md Adds Vietnamese Insights introduction.
src/​insights/​index.uk.md Adds Ukrainian Insights introduction.
src/​insights/​index.ru.md Adds Russian Insights introduction.
src/​insights/​index.md Uses the shared public image path.
src/​insights/​index.ko.md Adds Korean Insights introduction.
src/​insights/​index.ja.md Adds Japanese Insights introduction.
src/​insights/​index.es.md Adds Spanish Insights introduction.
src/​insights/​index.de.md Adds German Insights introduction.
src/​insights/​index.ar.md Adds Arabic Insights introduction.
src/​insights/​expression-problem.md Adds explicit video clip boundaries.
src/​index.zh.md Adds Simplified Chinese landing content and part titles.
src/​index.zh-hant.md Adds Traditional Chinese landing content and part titles.
src/​index.vi.md Adds Vietnamese landing content and part titles.
src/​index.uk.md Adds Ukrainian landing content and part titles.
src/​index.ru.md Adds Russian landing content and part titles.
src/​index.md Uses the shared public logo path.
src/​index.ko.md Adds Korean landing content and part titles.
src/​index.ja.md Adds Japanese landing content and part titles.
src/​index.es.md Adds Spanish landing content and part titles.
src/​index.de.md Adds German landing content and part titles.
src/​index.ar.md Adds Arabic landing content and part titles.
src/​denotational-design/​semantic-view.md Uses the shared public image path.
src/​denotational-design/​dependent-types.zh.md Adds Simplified Chinese dependent-types chapter.
src/​denotational-design/​dependent-types.ru.md Adds Russian dependent-types chapter.
src/​denotational-design/​dependent-types.es.md Adds Spanish dependent-types chapter.
src/​denotational-design/​dependent-types.de.md Adds German dependent-types chapter.
src/​denotational-design/​dependent-types.ar.md Adds Arabic dependent-types chapter.
src/​concepts/​referential_transparency.zh.md Adds Simplified Chinese referential-transparency chapter.
src/​concepts/​referential_transparency.zh-hant.md Adds Traditional Chinese referential-transparency chapter.
src/​concepts/​referential_transparency.vi.md Adds Vietnamese referential-transparency chapter.
src/​concepts/​referential_transparency.ru.md Adds Russian referential-transparency chapter.
src/​concepts/​referential_transparency.ko.md Adds Korean referential-transparency chapter.
src/​concepts/​referential_transparency.es.md Adds Spanish referential-transparency chapter.
src/​concepts/​referential_transparency.de.md Adds German referential-transparency chapter.
src/​concepts/​referential_transparency.ar.md Adds Arabic referential-transparency chapter.
src/​concepts/​operational_semantics.md Adds explicit video clip boundaries.
src/​concepts/​index.zh.md Adds Simplified Chinese Concepts introduction.
src/​concepts/​index.zh-hant.md Adds Traditional Chinese Concepts introduction.
src/​concepts/​index.vi.md Adds Vietnamese Concepts introduction.
src/​concepts/​index.uk.md Adds Ukrainian Concepts introduction.
src/​concepts/​index.ru.md Adds Russian Concepts introduction.
src/​concepts/​index.md Uses the shared public image path.
src/​concepts/​index.ko.md Adds Korean Concepts introduction.
src/​concepts/​index.ja.md Adds Japanese Concepts introduction.
src/​concepts/​index.es.md Adds Spanish Concepts introduction.
src/​concepts/​index.de.md Adds German Concepts introduction.
src/​concepts/​index.ar.md Adds Arabic Concepts introduction.
src/​concepts/​defunctionalization.zh.md Adds Simplified Chinese defunctionalization chapter.
src/​concepts/​defunctionalization.zh-hant.md Adds Traditional Chinese defunctionalization chapter.
src/​concepts/​defunctionalization.vi.md Adds Vietnamese defunctionalization chapter.
src/​concepts/​defunctionalization.ru.md Adds Russian defunctionalization chapter.
src/​concepts/​defunctionalization.ko.md Adds Korean defunctionalization chapter.
src/​concepts/​defunctionalization.ja.md Adds Japanese defunctionalization chapter.
src/​concepts/​defunctionalization.es.md Adds Spanish defunctionalization chapter.
src/​concepts/​defunctionalization.de.md Adds German defunctionalization chapter.
src/​concepts/​defunctionalization.ar.md Adds Arabic defunctionalization chapter.
src/​concepts/​cps.zh.md Adds Simplified Chinese continuation-passing chapter.
src/​concepts/​cps.zh-hant.md Adds Traditional Chinese continuation-passing chapter.
src/​concepts/​cps.vi.md Adds Vietnamese continuation-passing chapter.
src/​concepts/​cps.uk.md Adds Ukrainian continuation-passing chapter.
src/​concepts/​cps.ru.md Adds Russian continuation-passing chapter.
src/​concepts/​cps.ko.md Adds Korean continuation-passing chapter.
src/​concepts/​cps.ja.md Adds Japanese continuation-passing chapter.
src/​concepts/​cps.es.md Adds Spanish continuation-passing chapter.
src/​concepts/​cps.de.md Adds German continuation-passing chapter.
src/​concepts/​cps.ar.md Adds Arabic continuation-passing chapter.
src/​concepts/​branching.md Adds explicit video clip boundaries.
src/​about.zh.md Adds Simplified Chinese book overview.
src/​about.zh-hant.md Adds Traditional Chinese book overview.
src/​about.vi.md Adds Vietnamese book overview.
src/​about.uk.md Adds Ukrainian book overview.
src/​about.ru.md Adds Russian book overview.
src/​about.ko.md Adds Korean book overview.
src/​about.ja.md Adds Japanese book overview.
src/​about.es.md Adds Spanish book overview.
src/​about.de.md Adds German book overview.
src/​about.ar.md Adds Arabic book overview.
public/​fonts/​OFL.txt Includes the bundled font license.
package.json Defines build, development, checking, and test commands.
book.toml Configures localization and reader styling.
.gitignore Excludes installed Node dependencies.
.github/​workflows/​deploy.yml Integrates Node, browser tooling, and validation.
.github/​actions/​setup-rust/​action.yml Updates the compiler-cache setup action.

Review effort: Balanced

Comment thread web/mdbook.ts Resolved
Comment thread web/test/build.test.ts Resolved
Comment thread web/test/site.test.ts Resolved
Comment thread src/concepts/index.ar.md Resolved

Copy link
Copy Markdown
Contributor Author

@tgrospic The consolidated handover is ready at 4ed8cbd. Upstream CI and local validation both pass all 507 tests, with no failures or skips. Type checking and the production build also pass. The Pages publication step was skipped; this PR has not been merged or deployed.

I reviewed the current day/night, real-world, mobile and RTL layouts and retained your integrated design. The only additional changes after b2a797d are the README contributor credits, the full Tomislav Grospić spelling in book.toml, and the attribution rule in root AGENTS.md. Existing commit authorship is preserved.

Mobile checks use Android Chromium and iPhone WebKit browser profiles. I have Android hardware but no iPhone/iPad; physical Android Chrome and iOS Safari remain NOT TESTED.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ed8cbd28d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web/mdbook.ts Resolved
Comment thread theme/index.hbs Resolved
Comment thread web/reader.ts Resolved
Comment thread src/concepts/index.ar.md Resolved
Comment thread theme/index.hbs Resolved
Comment thread web/test/site.ts Resolved
Comment thread web/test/build.test.ts Resolved
Copilot AI balanced review requested due to automatic review settings October 28, 2026 21:16

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Subtle semantic, labeling, and grammatical concerns in the Korean and German translations require human review to judge their impact.

No open issues 🎉

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings October 28, 2026 21:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because findings about translation fidelity and a mismatched navigation label were omitted from the published review.

No open issues 🎉

Review effort: Balanced

Copy link
Copy Markdown
Contributor Author

The review follow-up is complete at 0019c7b. Exact-head upstream CI and the final local run both pass 530 tests, with zero failures, cancellations or skips. Type checking and the production build pass too. Each current inline finding has a fixing-commit reply and is resolved.

The two development-preview concerns from the latest Copilot summary are covered by a native mdBook fixture: startup finishes all editions before accepting the first request, and a real watched edit triggers a rebuild with normalized Windows paths. The handover instructions now describe these checks.

Firefox print diagnostics traced a console failure to the external YouTube iframe's cookie policy. Console failures are now scoped to the site's origin; site script/request checks remain strict, and the deliberately missing-font test still proves broken resources are reported. Physical Android Chrome and iOS Safari remain untested. The Pages publication step was skipped; no merge or deployment was performed.

Copilot AI balanced review requested due to automatic review settings October 29, 2026 10:09

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A backup-cleanup failure can reject a successful site replacement, causing the dev caller to skip module invalidation and reload despite changed files.

3 open issues

Review effort: Balanced

Comment thread web/mdbook.ts Resolved
Comment thread src/concepts/index.ko.md Resolved
Comment thread src/index.ar.md Resolved

Copy link
Copy Markdown
Contributor Author

@tgrospic One additional update in f4ce0b6 restores the localized repository introductions:

  • The English README now links to ten introductions under docs/README.<lang>.md, matching all eleven website editions. The descriptions reflect the current two reading worlds and chapter-local progress, with English build instructions kept as the shared maintenance reference.
  • Each introduction uses its matching language card and distinguishes our respective contributions with linked GitHub accounts. Tomislav Grospić, including ć, is preserved throughout.
  • All eleven cards were regenerated at their existing 1200 × 630 size with the same artwork/layout and corrected author spelling. Their editable source is now web/social-cards.ts; root AGENTS.md documents the localization conventions.

All eleven introductions pass GitHub Markdown rendering and local link checks. Type checking, the production build, and all 530 upstream CI tests pass on this commit: https://github.com/alux-network/alux-programming/actions/runs/40855286338. The reader bundle is byte-identical to the preceding version; nothing has been merged or deployed.

Copilot AI balanced review requested due to automatic review settings October 29, 2026 11:22

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because Markdown rewrite edge cases can alter literal code examples and leave media URLs incorrectly normalized inside admonitions.

No open issues 🎉

3 resolved since last review

Review effort: Balanced

Copy link
Copy Markdown
Contributor Author

Addressed the three new review comments in 975ef7e and 1fea1e0:

  • After a successful site replacement, backup-cleanup failure now reports the retained backup without rejecting publication, so Vite still invalidates transforms and reloads. The unit and real watched-edit regressions reproduced the failure before the fix and pass afterward; AGENTS.md records this boundary.
  • Corrected the Korean DD/concepts subject-object relationship and the Arabic statement that specifications are expressed as capability traits. Corresponding passages were reviewed across the ten translations; canonical English, links and code are unchanged.

The exact-head CI run passes all 531 tests, with zero failures or skips. Local typecheck, production build, focused regressions and 297 site/translation checks also pass. All three threads have fixing-commit replies and are resolved. No merge or deployment was performed.

Copilot AI balanced review requested due to automatic review settings October 29, 2026 12:45

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

Copy link
Copy Markdown
Contributor Author

Checked the Markdown boundary cases raised in the last review summary and fixed them in 9d4d784.

Image normalization is now an HTML-only native mdBook preprocessor after admonish and katex. CommonMark and HTML source positions restrict changes to actual image destinations and img src attributes. Literal code, comments, script text, data-src, image labels/titles and shared ordinary-link definitions are preserved. The parser dependencies are build-only; the reader bundle is byte-identical.

The added regressions reproduce failures in the old helper and cover indented/fenced/inline code, containers, reference images and exact HTML attributes. A fixture using the real configured preprocessor chain verifies images and code in English/Arabic chapter and print pages. The existing mixed HTML/Markdown fixture now includes the blank line needed to render both images; its path assertions are unchanged. AGENTS.md and the PR description record the new boundary.

The exact-head CI run passes all 536 tests, with zero failures or skips. Local typecheck, production build and the final 22 media/site checks also pass. The latest Copilot rereview did not execute because its quota was exhausted; this is not a new review approval. No merge or deployment was performed.

@tgrospic tgrospic added the enhancement New feature or request label Oct 29, 2026

@tgrospic tgrospic left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shixi-11 great work, and excellent responsiveness! Thank you for taking the review comments so quickly and so carefully.

This round makes the reader feel solid. Your place in the chapter now survives resizing and orientation changes, and the print page leaves the saved world alone. The keyboard help is translated, and a failed build no longer destroys the previous site. Fixing image paths with a proper mdBook preprocessor, instead of patching the rendered HTML, is exactly the direction this repo wants. The localized READMEs and the regenerated social cards complete the picture across all eleven languages.

Approving. 🚀

@tgrospic
tgrospic merged commit 173f8f8 into alux-network:master Oct 29, 2026
1 check passed

Copy link
Copy Markdown
Contributor Author

@tgrospic The reader follow-up is ready in #5, built on the mdBook architecture merged here. It covers the presentation and interaction gaps identified during visual review, plus the subsequent paging/audio findings. The final head d359330 passes all 611 tests: CI results. Root AGENTS.md and docs/reader-experience.md in #5 document the handoff, actual causes, our follow-up mistakes and prevention checks. Mobile results are simulations; physical-device acceptance is still separate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants