docs: migrate documentation site to levimc-kit (Impression, Craft)

[futrime]

Summary

This PR moves the LegacyScriptEngine docs (https://docs.levimc.org/LegacyScriptEngine/) from MkDocs Material 9.3 to levimc-kit 1.0.0. levimc-kit is the shared "Impression, Craft" design system (Monet colour fields + Minecraft pixel UI) and static docs engine that every LeviMC site now uses: Vite 8 + React 19 + react-router 7 + TypeScript + Tailwind CSS v4. Every URL is prerendered to real HTML for GitHub Pages and then hydrated.

• All markdown stays where it was. No page text changed; only the targets of broken or redirecting links changed, and their link text is unchanged.
• Every live URL, every old #heading deep link and the old #fn:N / #fnref:N footnote links still answer 200 with no redirect.

What changed

• App at the repository root (next to the old mkdocs.yml): kit/ (vendored levimc-kit 1.0.0, patches listed below), package.json + package-lock.json (npm), docs.config.ts, vite.config.ts, tsconfig.json. contentDir: 'docs'. The content is unchanged: 92 pages (46 en x.md + 46 zh x.zh.md), plus img/logo.png and img/ColorLog.png.
• Config ported 1:1 from mkdocs.yml:
  • The same nav tree, including apis/README.md → /LegacyScriptEngine/apis/, and the zh nav_translations (Home 主页, Tutorials 教程, APIs 接口). The seven API sub-groups use the { text, collapsed: true, items } form. Like Material without navigation.expand, only the group that holds the current page is open, so the current page is always visible in the sidebar.
  • Suffix i18n with zh under /zh/, directory URLs, and pymdownx heading ids (#-sql数据库, _1 duplicates).
  • Python-Markdown compatibility: hard breaks, 2–3-space list flattening, admonitions, footnotes, <details>, <u>, ~~.
  • Material-style tabs (navigation.tabs) and logo/favicon img/logo.png.
  • Edit links to edit/develop/docs/:path, and last-updated dates.
  • <title>: Page - LegacyScriptEngine, and just LegacyScriptEngine on the English home page, as on MkDocs.
  • Outline h2–h6, matching MkDocs' "Table of contents". The API entries in File, Basic, Command, DataBase and LanguageSupport are h5 headings.
• Removed: mkdocs.yml, requirements.txt, docs/overrides/main.html. The kit's root-only language redirect, which respects a stored choice, replaces the old redirect script.
• .github/workflows/build_docs.yml:
  • Triggers are the same as before: push on all branches, plus workflow_dispatch. The path list now covers docs/**, kit/** and the app files instead of mkdocs.yml.
  • The deploy condition is still refs/heads/develop && push.
  • Steps: fetch-depth: 0, Node 24 + npm ci → typecheck → build → internal linkcheck → upload-pages-artifact@v5 (dist/) → deploy-pages@v5.
  • The deploy job now runs in the github-pages environment (its branch policy allows develop) and in a pages concurrency group (cancel-in-progress: false).
• .gitignore: /dist/, /.kit/.
• README.md / README.zh.md: the docs links use the canonical trailing-slash URL.

Verification

All numbers come from the clean CI sequence (npm ci && npm run typecheck && npm run build), served with kit/scripts/serve-pages.mjs (GitHub Pages semantics).

• build: 92 pages, the themed 404, sitemap.xml + sitemap.xml.gz, and search indexes. There is one expected warning, for the escaped pseudo-tag <NBT object> (see below). find dist -type d -empty prints nothing.
• typecheck: tsc --noEmit clean.
• linkcheck (internal): 93 HTML files, 14,626 internal links. 0 broken, 0 needing a redirect, 0 missing anchors.
• linkcheck --external: 143 unique URLs, 0 broken. Everything that is not plainly ok:
  • ok-auth (51): GitHub edit links behind the sign-in wall.
  • blocked 429 (42): GitHub, rate-limited through the shared proxy. 41 of them are edit links to files that exist on develop. python/cpython/issues/83526 exists (checked via the API).
  • blocked 403: dev.mysql.com ×3. These are bot walls; all three load with 200 in headless Chromium with a browser User-Agent.
  • ok-redirect: the discord.gg invite (allowed).
  • redirect: https://bedrock.dev/zh/docs/stable/Molang answers 302 (temporary) → nextjs.bedrock.dev. All of bedrock.dev/zh does this. I left it on the canonical bedrock.dev URL on purpose: a temporary redirect to a nextjs. host is not a permanent move, and the English page would change the language of the link.
• url-parity --anchors: 92/92 live sitemap URLs answer 200 with 0 redirects, and every live heading id exists locally. These also answer 200/0 both live and locally: sitemap.xml, sitemap.xml.gz, img/logo.png, img/ColorLog.png, index.html, zh/index.html.
  • https://docs.levimc.org/LegacyScriptEngine/apis/ScriptAPI/Logger/ is hard-coded in src/legacy/api/LoggerAPI.cpp. It answers 200 with 0 hops, so the C++ code is unchanged.
  • Footnote ids match Python-Markdown (fn:1, fnref:1, …).
• Structure vs live: I compared element counts per page (blockquote/table/pre/details/headings/lists/…). Left: the documented list re-nesting below, the i18n footnote fences, the Economy emoji image and the NBT.zh ** typo. There is no empty blockquote and no extra code block.
• text-parity (live selector article.md-content__inner): 92 pages, 83 identical, 99.986 % word similarity. Every remaining difference is listed under Known renderer differences.
• smoke: 11/11 passed: no console or hydration errors, SPA navigation, theme persistence, Ctrl+K search ("listen" → 21 results), en→zh locale switch, root-only language redirect, copy button, 390 px drawer, and the themed 404. There are no content tabs in these docs.
• Sidebar / drawer / TOC:
  • 88/88 sidebar pages show the current page's link in view, at 1440×900 on load and in the 390×844 drawer. At most one API group is open.
  • SPA navigation into a collapsed group opens it and reveals the link.
  • On the 114-entry Player pages, the highlighted "On this page" entry stays in view at every scroll position (en + zh).
• Header: the full "LegacyScriptEngine" title shows from 360 px up, in both locales and both themes. Below 360 px it is ellipsized.
• Screenshots (all reviewed) are in /home/futri/levimc-work/u4-lse/screens/:
  • Round 1, fix-r1/, light + dark at 1440 and 390: home, home-zh, scripthelp, tutorial-zh, systeminfo, player-zh, nbtvalue, command, plus drawer-systeminfo-{light,dark}-390.png and toc-follow-player-light-1440.png.
  • Initial:
    • home-*, zh-home-*, zh-blockevents-*, player-*, database-*
    • command-tip-*, languagesupport-tip-*, gameutils-*, gameutils-format-*
    • blockevents-details-*, i18n-footnotes-*, file-toc-*, scripthelp-img-*, notfound-*
    • live-home-light-1440.png, live-database-light-1440.png

Link fixes

Link text is unchanged everywhere; only the targets below changed.

Where	Old → new	Why
apis/DataAPI/DataBase.md	https://www.google.com/search?q=https://gitee.com/Y_oyo → https://gitee.com/Y_oyo	Mangled link. The zh page already used the gitee URL.
apis/DataAPI/DataBase.md	https://www.google.com/search?q=%23connection-parameters → #connection-parameters	Mangled in-page anchor. The anchor exists live and locally; the zh page already used #连接参数.
apis/DataAPI/DataBase.md	https://www.google.com/search?q=%23execute-sql-and-get-result-set → #execute-sql-and-get-result-set	Same as above.
apis/ScriptAPI/i18n(.zh).md ×4	https://fmt.dev/latest/syntax.html → https://fmt.dev/latest/syntax/	The old URL is 404; the new one is fmt's current syntax page.
apis/GameAPI/Player.md ×13, Player.zh.md ×13	https://docs.microsoft.com/{en-us,zh-cn}/minecraft/creator/scriptapi/mojang-gametest/simulatedplayer#x → https://learn.microsoft.com/{en-us,zh-cn}/minecraft/creator/scriptapi/minecraft/server-gametest/simulatedplayer?view=minecraft-bedrock-experimental#x	The old URL took 3 redirects. The new one is the final target and matches the existing #respawn/#rotatebody links. All 13 anchors were verified on both locale pages.
apis/GameAPI/Block.zh.md	https://zh.minecraft.wiki/w/粒子#类型 → https://zh.minecraft.wiki/w/基岩版粒子#类型	粒子 is now a disambiguation page without #类型. 基岩版粒子 answers 200 with 0 hops, has id="类型" and lists heart_particle, the example the text cites. The en link (Particles#Types_of_particles) is still valid.
tutorials/create_your_first_plugin(.zh).md	https://atom.io/ → https://github.blog/news-insights/product-news/sunsetting-atom/	atom.io was sunset and 301s (3 hops) to this announcement, which is its final URL.
apis/LanguageSupport(.zh).md	https://docs.levimc.org/LeviLamina → https://docs.levimc.org/LeviLamina/	Missing trailing slash (301).
apis/SystemAPI/Network.zh.md	https://github.com/LiteLDev/LiteLoaderBDSv2/blob/v2/main/test/UnitTest.js → https://github.com/LiteLDev/LiteLoaderBDS/blob/v2/main/test/UnitTest.js	The repo was renamed (301). The file exists on v2/main.
README.md, README.zh.md	https://docs.levimc.org/LegacyScriptEngine → https://docs.levimc.org/LegacyScriptEngine/	Missing trailing slash (301).

No other markdown edits: the earlier NBTValue backtick edit was reverted, and the kit now reproduces Python-Markdown's code-span pairing.

Known renderer differences

Text (the 9 text-parity pages). Each one is a source quirk that MkDocs rendered lossily; the kit shows what the author wrote.

1. Array<NBT object> / Array<NBT 对象> (NBTList) and Object<string, NBT Object> (NBTCompound), en + zh: MkDocs let the browser swallow these pseudo-tags, so it showed only "Array" / "Object". The kit escapes them and shows the full type (build warning escaped non-HTML tags).
2. hh:mm:ss (Economy, en + zh): pymdownx.emoji turned :mm: into an emoji image on the live site, which therefore shows "hhss". The kit shows hh:mm:ss.
3. Footnotes in ScriptAPI/i18n (en + zh): the footnote fences are indented by 2 spaces, so neither renderer keeps them inside the footnote. MkDocs rendered them as inline code "json { … }". The kit renders them as real JSON code blocks in the same position. The only text lost is the word "json", which becomes the code title. The kit also adds a "Footnotes" entry to the outline.
4. NBT.zh unbalanced **: **N**amed … **T**ags**）** and **NBT标签 ** are source typos. pymdownx.betterem showed Tags） and *NBT标签 *; CommonMark shows Tags**）** and **NBT标签 **.

Structure only (same text). In these places Python-Markdown's list quirks re-nest a line, or move it out of its list. The kit follows the authored indentation:

5. "Return value" bullets after a nested "Parameters" list. Un-indented - Return value… / - Intercept event items after a nested parameter list:
   • Live absorbed them into the nested list; the kit keeps them at the top level, as written.
   • Pages: ScriptHelp (setTimeout/setInterval, en + zh), Command (lines 31–38), FormBuilder (lines 28/38/50), EntityEvents (line 143), Player (lines 698/974), and the zh siblings.
   • In ScriptHelp the kit also nests "If it returns Null…" under "Return value type", where it is indented.
6. zh EntityEvents, Wither AAbb/aaBB items: these stay inside the list locally; live breaks out of it.
7. NBTCompound (en) line 251: > Only complete top-level… directly follows a list item without a blank line. Live puts the quote inside the <li>; the kit renders it right after the list.

Other:

8. Admonition titles stay MkDocs-style ("Warning", "Tip", "Note") on zh pages too, exactly as live.
9. 404 page <title>: "This page wandered off - LegacyScriptEngine" (Material used the bare site name).
10. MkDocs internals that nothing links to now 404: search/search_index.json and assets/images/favicon.png. The favicon is img/logo.png, as before.

Kit patches

All are in the vendored kit/ and are generic; please upstream them. Every one is covered by the verification above.

File	Change	Why
kit/docs/app/docs.css	Indentation for .kit-toc-list li[data-level="3"|"4"] a	This site's outline: [2, 6] (MkDocs' h5 entries) went past the styled depths 0–2.
kit/docs/app/docs.css (≤420 px header)	Below 420 px: drop the 9.5rem title cap, brand gap 0.5rem / margin 0, hide the locale chevron (the globe stays). Title is 0.9375rem at ≤380 px and 0.8125rem at ≤365 px.	The 390 px header ellipsized "LegacyScriptE…". The full name now fits from 360 px.
kit/docs/app/components/reveal.ts (new), Sidebar.tsx, MobileDrawer.tsx, Toc.tsx	revealIn() scrolls only the given scroll container (never the page), instantly, so there is no motion. Sidebar and drawer centre the active link on load, after navigation and when the drawer opens. The TOC keeps the highlighted entry inside the sticky column.	The current page and the current heading went off-screen on long sidebars and outlines (the TOC follow is Material's toc.follow).
kit/docs/node/markdown/preprocess.ts	python-markdown compat: (a) 5+ spaces after a list marker collapse to one space; (b) after a > line, the rest of the block stays in the quote, but headings, rules and containers split it; (c) on lines with a 2+ backtick run, code spans are paired with Python-Markdown's BACKTICK_RE and re-emitted as equivalent CommonMark spans, only when the result verifiably matches. Indented-code lines are skipped.	(a) SystemInfo rendered a prose bullet as a "Text Only" code block. (b) The zh tutorial showed an empty quote bar and an unquoted intro. (c) NBTValue's Number` `` without a source edit. All three now match the live HTML structure.
kit/docs/node/markdown/render.ts	When compat is python-markdown, footnote ids and hrefs use Python-Markdown's form: fn:N, fnref:N, fnrefK:N.	Old #fn:1 deep links keep working.
kit/docs/shared/head.ts	For urlStyle: 'directory', the site-root page gets the bare site title (Material's is_homepage). The 404 title uses titleTemplate. Function replacers prevent $ expansion.	<title> parity with MkDocs. LeviLamina has the same home-title difference.
kit/docs/node/vite.ts	Directory-style (MkDocs) sites also emit sitemap.xml.gz.	The live URL keeps answering 200 for crawlers that registered it.
kit/docs/prerender.mjs	The cleanup loop uses rmdirSync instead of rmSync, which threw EISDIR.	An empty dist/kit/docs/app/ was shipped in the Pages artifact.

Follow-ups

• Kit default: the kit opens every first-level sidebar group, even in MkDocs tabs mode. Its own SidebarData.expand docs say MkDocs opens only the active path. Defaulting MkDocs-mode groups to collapsed would let LeviLamina (same Material features) drop the per-site collapsed: true.
• Home hero (coordinator decision): index(.zh).md render with the doc layout, like LeviLamina's port. A layout: home PaintedHero would mean restructuring the home markdown (H1 and lead move into frontmatter), so I did not do it here.
• Kit: footnote-id mapping uses remark's lower-cased label. Only numeric footnotes exist today, so this changes nothing yet.
• Kit: the sidebar reveal runs on navigation, not when a narrow window is widened.
• bedrock.dev/zh/... currently answers 302 to nextjs.bedrock.dev. Revisit if bedrock.dev makes that permanent.

🤖 Generated with Claude Code

[futrime]

Review round 1: fixes (commit f752a88)

Fixed

1. Sidebar showed every API group open, so the current page's link was off-screen on 49/88 pages. The seven API sub-groups now start collapsed ({ text, collapsed: true, items }), as in Material without navigation.expand. A kit patch also scrolls the active link into view in the sticky sidebar and in the drawer. Result: 0/88 pages have the link out of view, both at 1440×900 and in the 390×844 drawer.

2. zh tutorial had an empty blockquote and an unquoted intro. Kit python-markdown compat now treats a line after a > line as part of the quote, as Python-Markdown does. The intro is quoted again, as live. No source edit.

3. and 9. SystemInfo rendered a prose bullet as a "Text Only" code block. Kit compat now collapses 5+ spaces after a list marker to one space. It renders as a normal bullet; that page's <pre> count matches live (0).

4. Title was clipped in the 390 px header. Kit CSS for ≤420 px:

   • removed the 9.5rem cap
   • tightened the brand gap and margin
   • hid the locale chevron (the globe stays)
   • stepped the title font down at ≤380 px and ≤365 px

   The full "LegacyScriptEngine" now shows from 360 px up, in en/zh and light/dark.

5. Titles. The English home page is now LegacyScriptEngine, as on MkDocs (is_homepage). The 404 title uses the titleTemplate.

6. "On this page" did not follow long pages. Kit Toc keeps the highlighted entry visible inside the sticky column. On Player (114 entries) it is out of view at 0 of 7 scroll positions.

7. and 10. Structural differences. The list re-nesting and the NBTCompound quote placement are now listed under "Known renderer differences".

8. Footnote ids. Kit now emits Python-Markdown footnote ids (fn:1, fnref:1), so old deep links resolve.

9. zh particle link → https://zh.minecraft.wiki/w/基岩版粒子#类型. It answers 200 with 0 hops, has id="类型" and lists heart_particle.

10. sitemap.xml.gz is emitted again; it answers 200 locally, as live.

11. Deploy job now has environment: github-pages with the page URL output (the environment's branch policy allows develop), and the pages concurrency group.

12. Duplicate CI runs. Dropped the pull_request trigger, back to the original triggers; push already covers every branch.

13. NBTValue source edit reverted. The kit now pairs backticks like Python-Markdown, so the output is <code>Number`, byte-identical to live, with the markdown untouched.

14. Empty dist/kit/docs/app/. Fixed rmdirSync in kit/docs/prerender.mjs. find dist -type d -empty now prints nothing.

Not fixed

• 6. Painted hero on the home page. This is a coordinator decision. It needs the home markdown restructured (H1 and lead moved into layout: home frontmatter). LeviLamina's sibling port also keeps its home on the doc layout, so I left both sites consistent. It is listed under Follow-ups.
• 18. bedrock.dev/zh/docs/stable/Molang. I re-checked it: still a 302 (temporary), and all of bedrock.dev/zh redirects to nextjs.bedrock.dev. I kept the canonical URL, because pointing zh readers to the English page would change the link's language. It stays documented.

Code review (/code-review) findings

• Fixed: a lazy quote line indented 4+ spaces could become code inside the quote; it is now trimmed.
• Fixed: the duplicated double-rAF reveal logic is now afterPaint() in reveal.ts.
• Left as Follow-ups: the kit-level default for collapsed MkDocs groups, case-sensitive named footnote labels (none are used), and the reveal on window widening.

Re-verified from a clean npm ci:

• typecheck and build: clean (1 expected <NBT object> warning)
• linkcheck: 14,626 internal links, 0 broken / 0 redirect / 0 missing anchors
• linkcheck --external: 0 broken; only the documented bedrock.dev/zh 302
• url-parity --anchors: 92/92 at 200 with 0 hops, plus sitemap.xml.gz, img/* and index.html forms
• text-parity: 83/92 pages identical, 99.986 %; every difference is documented
• smoke: 11/11
• sidebar, drawer and TOC checks: described above

The content HTML changed on exactly 7 pages compared with the previous build, all of them intended.

Kit patches (all listed in the PR body for upstreaming): docs.css, reveal.ts (new), Sidebar.tsx, MobileDrawer.tsx, Toc.tsx, preprocess.ts, render.ts, head.ts, vite.ts, prerender.mjs.

Screenshots: /home/futri/levimc-work/u4-lse/screens/fix-r1/, light + dark at 1440 and 390 px:

• home and home-zh
• scripthelp, tutorial-zh, systeminfo, player-zh, nbtvalue, command
• drawer-systeminfo
• toc-follow-player

🤖 Generated with Claude Code