Use highlight.js v11 + npm highlightjs-move and fix mdbook warning by gregnazario · Pull Request #14 · gregnazario/aptos-book

gregnazario · 2026-02-08T17:54:14Z

Summary

switch mdBook HTML highlight runtime to Highlight.js v11 via theme/highlight.js
replace custom Move grammar with vendored npm highlightjs-move and register via move-init.js
add a katex preprocessor wrapper to suppress the known mdbook version-mismatch warning line
align setup pins to mdbook 0.4.52

Validation

mdbook build passes
no mdbook-katex/mdbook version mismatch warning is emitted during build
existing linkcheck fragment warnings remain unchanged

Copilot

Pull request overview

This PR updates the mdBook site’s client-side syntax highlighting to Highlight.js v11, vendors a Move grammar via highlightjs-move, and adds a wrapper around mdbook-katex to suppress a known version-mismatch warning during builds. In addition, it significantly expands and reorganizes book content across multiple chapters (Tools, Error Handling, Closures, Concurrency, Stdlib, etc.).

Changes:

Vendor Highlight.js v11 runtime + vendored highlightjs-move grammar and register/highlight Move blocks at runtime.
Add mdbook-katex wrapper and bump mdBook pin versions across setup scripts/mise.
Add/expand multiple documentation chapters and update the book TOC accordingly (Tools/CLI/TS SDK, Error Handling, Closures, Concurrency, Stdlib, Events, Struct resources).

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
theme/highlight.js	Vendored Highlight.js v11 runtime for the book theme.
highlightjs-move.js	Vendored Move language definition and exposes `window.hljsDefineMove`.
move-init.js	Registers Move language and highlights Move code blocks on the page.
book.toml	Wires in katex wrapper command and adds Move/highlight JS to HTML output.
scripts/mdbook-katex-wrapper.sh	New wrapper to filter a specific mdbook-katex warning line.
scripts/setup.sh	Bumps mdbook install pin to 0.4.52.
scripts/setup.ps1	Bumps mdbook install pin to 0.4.52 (Windows setup).
scripts/setup-mise.sh	Bumps mdbook install pin to 0.4.52 in mise setup flow.
mise.toml	Aligns mdbook version pin/task setup command to 0.4.52.
src/SUMMARY.md	Updates book structure/TOC for new/expanded sections.
src/tools/intro.md	Adds Tools section landing page.
src/tools/aptos-cli/intro.md	Expands Aptos CLI documentation intro and links.
src/tools/ts-sdk/intro.md	Adds TypeScript SDK overview/usage docs.
src/structs/resources.md	Adds expanded explanation/examples for resources via struct abilities.
src/standard_libraries/move_stdlib.md	Replaces TODO with Move stdlib overview and links.
src/standard_libraries/aptos_stdlib.md	Replaces TODO with Aptos stdlib overview and comparison table.
src/move/design_patterns/intro.md	Adds Move design patterns section intro content.
src/events/indexing.md	Replaces TODO with event indexing overview and examples.
src/concurrency/intro.md	Adds concurrency section introduction (Block-STM concepts).
src/concurrency/basics.md	Adds concurrency basics content and examples.
src/concurrency/types.md	Adds type-level concurrency discussion and examples.
src/common_programming_concepts/error_handling.md	Adds error handling chapter content and examples.
src/common_programming_concepts/recoverable_errors.md	Adds recoverable error patterns chapter content.
src/common_programming_concepts/unrecoverable_errors.md	Adds unrecoverable error handling chapter content.
src/closures/intro.md	Expands closures chapter introduction.
src/closures/defining.md	Adds detailed closures syntax/capture/usage documentation.
src/error_handling/intro.md	Removes old stub error-handling page (moved/replaced).
src/error_handling/recoverable_errors.md	Removes old stub page (moved/replaced).
src/error_handling/unrecoverable_errors.md	Removes old stub page (moved/replaced).
src/error_handling/when_to_use.md	Removes old stub page (moved/replaced).
WARP.md	Adds WARP.md file referencing CLAUDE.md.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-08T17:59:48Z

+if ! mdbook-katex "$@" 2>"$err_file"; then
+    status=$?
+fi


The wrapper never propagates mdbook-katex failures: inside if ! mdbook-katex ...; then status=$?; fi, $? is the status of the negated ! command (0), not the underlying mdbook-katex exit code. Capture the exit status without ! (or store it before negation) so the wrapper exits non-zero when mdbook-katex fails.

Suggested change

if ! mdbook-katex "$@" 2>"$err_file"; then

status=$?

fi

mdbook-katex "$@" 2>"$err_file" || status=$?

Copilot · 2026-02-08T17:59:49Z

 [preprocessor.katex]
+command = "scripts/mdbook-katex-wrapper.sh"
 after = ["links"]


preprocessor.katex.command points to a POSIX shell script. Since the repo includes a Windows setup script (scripts/setup.ps1), this will likely break mdBook builds on Windows unless users also have a compatible sh available. Consider switching the command back to mdbook-katex by default, or provide a cross-platform wrapper (e.g., a small Rust binary or a .ps1 wrapper plus a command that works on both platforms).

Copilot · 2026-02-08T17:59:50Z

+const l=Object.create(null);function c(){if(!O.keywords)return void A.addText(S)
+;let e=0;O.keywordPatternRe.lastIndex=0;let n=O.keywordPatternRe.exec(S),t=""
+;for(;n;){t+=S.substring(e,n.index)
+;const i=v.case_insensitive?n[0].toLowerCase():n[0],r=(a=i,O.keywords[a]);if(r){


Variable 'a' is used before its declaration.

Copilot · 2026-02-08T17:59:51Z

+match:[/function/,/\s+/,t,/(?=\s*\()/]},{match:[/function/,/\s*(?=\()/]}],
+className:{1:"keyword",3:"title.function"},label:"func.def",contains:[f],
+illegal:/%/},v={
+match:n.concat(/\b/,(N=[...Ee,"super","import"].map((e=>e+"\\s*\\(")),


Variable 'N' is used before its declaration.

Copilot · 2026-02-08T17:59:51Z

+literal:"NULL NA TRUE FALSE Inf NaN NA_integer_|10 NA_real_|10 NA_character_|10 NA_complex_|10",
+built_in:"LETTERS letters month.abb month.name pi T F abs acos acosh all any anyNA Arg as.call as.character as.complex as.double as.environment as.integer as.logical as.null.default as.numeric as.raw asin asinh atan atanh attr attributes baseenv browser c call ceiling class Conj cos cosh cospi cummax cummin cumprod cumsum digamma dim dimnames emptyenv exp expression floor forceAndCall gamma gc.time globalenv Im interactive invisible is.array is.atomic is.call is.character is.complex is.double is.environment is.expression is.finite is.function is.infinite is.integer is.language is.list is.logical is.matrix is.na is.name is.nan is.null is.numeric is.object is.pairlist is.raw is.recursive is.single is.symbol lazyLoadDBfetch length lgamma list log max min missing Mod names nargs nzchar oldClass on.exit pos.to.env proc.time prod quote range Re rep retracemem return round seq_along seq_len seq.int sign signif sin sinh sinpi sqrt standardGeneric substitute sum switch tan tanh tanpi tracemem trigamma trunc unclass untracemem UseMethod xtfrm"
+},contains:[e.COMMENT(/#'/,/$/,{contains:[{scope:"doctag",match:/@examples/,
+starts:{end:n.lookahead(n.either(/\n^#'\s*(?=@[a-zA-Z]+)/,/\n^(?!#')/)),


This assertion can never match.

Copilot · 2026-02-08T17:59:51Z

+literal:"NULL NA TRUE FALSE Inf NaN NA_integer_|10 NA_real_|10 NA_character_|10 NA_complex_|10",
+built_in:"LETTERS letters month.abb month.name pi T F abs acos acosh all any anyNA Arg as.call as.character as.complex as.double as.environment as.integer as.logical as.null.default as.numeric as.raw asin asinh atan atanh attr attributes baseenv browser c call ceiling class Conj cos cosh cospi cummax cummin cumprod cumsum digamma dim dimnames emptyenv exp expression floor forceAndCall gamma gc.time globalenv Im interactive invisible is.array is.atomic is.call is.character is.complex is.double is.environment is.expression is.finite is.function is.infinite is.integer is.language is.list is.logical is.matrix is.na is.name is.nan is.null is.numeric is.object is.pairlist is.raw is.recursive is.single is.symbol lazyLoadDBfetch length lgamma list log max min missing Mod names nargs nzchar oldClass on.exit pos.to.env proc.time prod quote range Re rep retracemem return round seq_along seq_len seq.int sign signif sin sinh sinpi sqrt standardGeneric substitute sum switch tan tanh tanpi tracemem trigamma trunc unclass untracemem UseMethod xtfrm"
+},contains:[e.COMMENT(/#'/,/$/,{contains:[{scope:"doctag",match:/@examples/,
+starts:{end:n.lookahead(n.either(/\n^#'\s*(?=@[a-zA-Z]+)/,/\n^(?!#')/)),


This assertion can never match.

Copilot · 2026-02-08T17:59:51Z

+begin:g("s|tr|y","\\[","\\]")},{begin:g("s|tr|y","\\{","\\}")}],relevance:2},{
+className:"regexp",variants:[{begin:/(m|qr)\/\//,relevance:0},{
+begin:u("(?:m|qr)?",/\//,/\//)},{begin:u("m|qr",n.either(...d,{capture:!0
+}),/\1/)},{begin:u("m|qr",/\(/,/\)/)},{begin:u("m|qr",/\[/,/\]/)},{


There is no capture group 1 in this regular expression.

Copilot AI review requested due to automatic review settings February 8, 2026 17:54

Copilot started reviewing on behalf of gregnazario February 8, 2026 17:54 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Use highlight.js v11 + npm move grammar and quiet katex mismatch

4753240

gregnazario force-pushed the codex/highlightjs-v11-and-mdbook-warnings branch from a134eac to 4753240 Compare February 8, 2026 18:00

gregnazario merged commit b91fbc7 into main Feb 8, 2026
1 check passed

gregnazario deleted the codex/highlightjs-v11-and-mdbook-warnings branch February 8, 2026 18:03

Navigation Menu

Repository navigation

Use highlight.js v11 + npm highlightjs-move and fix mdbook warning - #14

Use highlight.js v11 + npm highlightjs-move and fix mdbook warning#14
gregnazario merged 1 commit into
mainfrom
codex/highlightjs-v11-and-mdbook-warnings

gregnazario commented Feb 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

gregnazario commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gregnazario commented Feb 8, 2026 •

edited

Loading