Repository navigation
feat: Add multilingual mdBook reading worlds - #4
Conversation
fix(reader): Refine reading continuity and add cross-browser acceptance
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
🟡 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
Stage replacement output before publishing · New Test repeatability of the complete mdBook and Vite build · New Add negative tests for language, direction, and edition removal · New Preserve the correct subject-object relationship in translation · New Use the correct term for mixed-paradigm systems · New
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
|
@tgrospic The consolidated handover is ready at I reviewed the current day/night, real-world, mobile and RTL layouts and retained your integrated design. The only additional changes after 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. |
There was a problem hiding this comment.
💡 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".
|
The review follow-up is complete at 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. |
|
@tgrospic One additional update in
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. |
|
Addressed the three new review comments in 975ef7e and 1fea1e0:
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. |
There was a problem hiding this comment.
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.
|
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 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
left a comment
There was a problem hiding this comment.
@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 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 |


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-wsintegration, 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.mdrecords handover and localization conventions. Browser automation covers desktop engines and mobile profiles; physical-device acceptance remains outstanding.