Merged
Conversation
Replaces the Sphinx + sphinx-rtd-theme stack with Astro 6 + Starlight 0.38, served as static HTML on GitHub Pages via Actions. What changed: - Astro Starlight project at the repo root (package.json, astro.config.mjs, tsconfig.json, src/content/docs, src/styles/brand.css, src/grammars). - 25 RST pages converted to Markdown via pandoc + a small Python pass that rewrites GFM alerts to Starlight asides, re-fences indented code blocks as ```hocon (or ```java where appropriate), inlines pandoc figure HTML as MD images, and points image URLs at /img/. - Static assets moved from _static/ to public/img/ and src/assets/. - Custom HOCON TextMate grammar registered with Shiki via expressiveCode so ```hocon code blocks render with full token colours. - Light/dark themes (github-light/github-dark) switched in the header from the Starlight default toggle - no extra plugins needed. - Splash homepage with hero, action buttons, and a CardGrid of section entry points. - Locale config primed for adding Russian later: defaultLocale=en, root locale wired, ru entry commented out in astro.config.mjs. - GitHub Actions workflow (.github/workflows/deploy.yml): Node 22, npm ci, astro build, upload-pages-artifact, deploy-pages on push to main. What was removed: - conf.py, Makefile, make.bat, index.rst, advanced/, dev/, general/, start/, _static/, _includes/, the pre-built docs/ output. Build status: `npm run build` produces 27 HTML pages, a Pagefind search index, and sitemap-index.xml. Cross-references that were :ref: / :doc: roles in RST land as best-effort relative anchors and will need a follow-up pass to resolve.
Astro 6 does not auto-prepend `base` to raw URLs inside Markdown, so paths like `/img/foo.png` 404 in dev/build under `base: '/docs/'`. Rewrites all image references in src/content/docs/ to `/docs/img/...` and documents the convention in README.
`src/assets/favicon.ico` is a multi-resolution Windows icon, which Astro's image pipeline (sharp) can't process - the rendered <img> ended up without a src, leaving only the alt text. Extracted a 64x64 PNG via sips and pointed Starlight's logo config at it. Favicon stays as `.ico` because browsers handle that natively.
Adds `ru` next to the root English locale in Starlight config. Pages without a Russian translation fall back to English with a "translate this page" notice from Starlight; only `start/tips.md` is provided in Russian as a working example. The language picker appears in the header automatically when more than one locale is configured. `defaultLocale` switched from "en" to "root" because Starlight requires it to match a locale key, and English now lives at the root locale.
Demo - src/content/docs/demo/components.mdx walks through Tabs, Steps, FileTree, Badge, LinkCard, Aside variants, and Expressive Code line markers/diff/filename/word-level highlighting. Each section shows the plain Markdown rendering first, then the same content via the Starlight component, so the visual delta is obvious. Infra - .github/workflows/lychee.yml runs weekly + on demand, builds the site, walks every link in dist/ via Lychee, opens an issue when failures show up. - .github/workflows/lint.yml runs cspell and markdownlint-cli2 on PRs and pushes to main. .cspell.json and .cspell-words.txt seed a project dictionary; .markdownlint-cli2.jsonc relaxes line-length and inline-HTML rules that fight Starlight components. Changelog - New `changelog` content collection at src/content/changelog/. src/content/docs/changelog/index.mdx renders entries newest-first. - src/pages/feed.xml.ts produces RSS 2.0 at /docs/feed.xml. - Sidebar gets a Changelog link at the bottom. - One seed entry covers the migration itself.
- start/how-to: rewritten as MDX with <FileTree> for the menus folder layout, <Steps> for the four-stage tutorial flow, <CardGrid> +<LinkCard> for the "where to next" footer, <Aside> + line/word highlighting on progressive HOCON snippets. Cross-references that pandoc left as bare anchor text now point at real /docs/ paths. - developers/general: rewritten as MDX with <Tabs> for Maven / Gradle (Groovy) / Gradle (Kotlin DSL) / no-build-system, <Steps> for the integration walk-through, <Tabs> again for the two ways to obtain the plugin instance. API version bumped 1.14 -> 1.16. - start/faq: rewritten as MDX, broken anchor links replaced with proper /docs/ paths, <CardGrid> at the bottom links to Hocon/How to/Tips/Examples. - advanced/generation: <Steps> wrapper around the four-stage intro; 4-space indented placeholder block fenced as ```text so MDX stops reading it as JSX. - advanced/input: <Steps> around the seven-stage extractor algorithm, same fencing fix. - Stray RST <div class="hint|attention|seealso"> remnants converted to Starlight asides (:::tip / :::caution / :::note[See also]) in advanced/templates, advanced/input, advanced/drag-and-drop, general/item-format, general/examples, general/actions.
Default --sl-content-width is 45rem; the right TOC column is computed as `(viewport - content - left-sidebar) / 2 + left-sidebar`, so widening content shrinks the TOC automatically. Bumped to 56rem (896px) which fits typical HOCON snippets and tables without horizontal scroll. Tightens the TOC explicitly in the 1152-1280px range where the new content width starts to crowd.
Fixed across all .md / .mdx pages in src/content/docs/:
1. Empty-link placeholders. Pandoc converted RST :ref:\`name<x>\` into
"[name]()\<x\>" which renders as an empty link followed by escaped
angle brackets. These are now wrapped as inline code "\`name_<x>\`"
matching the placeholder convention used elsewhere.
2. Span wrappers. RST :title-ref: roles came out as
"<span class=\"title-ref\">X</span>". Stripped the wrappers; tokens
become inline code, "here \<URL\>" forms become proper Markdown
links.
3. Escaped placeholders inside table cells. "\<world\>", "\_", "\>="
etc. unescaped; placeholder forms like "%foo_<bar>%" wrapped in
backticks so they render as code regardless of parser strictness.
4. Definition-list residue. Bare "\<key\>" terms turned into inline
code "\`<key>\`".
5. Stray escapes elsewhere ("if -\> then -\> else") unescaped.
One inventory-type sentence in general/menu-structure.md needed a
manual rewrite; the inner had a literal "\<" that the regex pass
couldn't unwrap cleanly.
Previous cleanup pass wrapped placeholder forms like %foo_<bar>% in backticks for safety. Inside Markdown tables that renders as code with a background, which clashes with surrounding plain-text rows. Reverts the wrapping inside table cells (lines containing 2+ pipes), keeping the original escaped style: "%foo\_\<bar\>%". Backticks remain wherever placeholders appear in regular prose - that context still benefits from the code rendering.
The earlier cleanup pass unescaped \<x\> -> <x> inside tables, expecting to wrap the result in backticks. Tables that ended up plain (no backtick wrap) lost their content on render because Markdown treated <foo> as an HTML tag. Re-escapes any <token> shape inside cells (letters, digits, spaces, dots, colons, hyphens) to \<token\>, plus the underscores that would trip italic when they touch the escaped bracket.
The English docs were stuck at the 1.16-era surface — Types,
Handlers, AbstractMenusProvider, no addon system, hardcoded API
version, version-1.12 caveats everywhere. This commit rewrites the
developer-facing pages on the new SPI and sweeps the operator pages
for legacy version cruft.
Major rewrites:
developers/general.mdx AbstractMenusApi.get(), JitPack as primary
artifact source (anonymous), GH Packages
as authenticated alternative
developers/handlers.md ProviderRegistry / ProviderSection<T>;
multi-provider, priority, config default,
owner-based cleanup
developers/own-types.md api.actions().register(...) shape; fixed
broken ```hocon code fences wrapping Java
developers/serializers.md api.serializers().register; correct fences
New pages:
developers/addons.mdx Path 1 vs Path 2, MenuExtension lifecycle,
addon.conf reference, /am addons cheatsheet
developers/migration.mdx every old API call mapped to its 2.0
replacement
general/commands.md /am, /am addons, /var, /varp reference
start/installation.mdx requirements, install, config.conf reference
Updated:
index.mdx /am addons in commands; addon + provider
concepts; "Extensible" card
start/faq.mdx addon install Q, providers Q, click-cooldown
vs click-debounce Q
start/tips.md /am addons rescan, MiniMessage, /var CLI
general/activators.md useWorldGuard (was: worldGuard); drop 1.12
numeric-id note
general/item-format.md clickCooldown is in milliseconds, not ticks;
drop 1.12-1.13 caveats
general/rules.md drop ancient version refs; replace stale JS
engine warning with the bundled-Nashorn note
general/text-colors.md drop 1.14 reference; expand MiniMessage
section with click/hover examples and the
useMiniMessage rationale
general/examples.md drop 1.13 caveat
developers/variables.md AbstractMenusApi.get().variables();
fix bogus expiry math example
developers/utils.md providers().placeholders().resolve();
BukkitTasks.runForEntity for Folia
Sidebar:
Add start/installation, general/commands, developers/addons,
developers/migration. Reorder developers section so addons + own-types
+ handlers come before serializers (workflow-first).
Changelog:
Add 2.0.0-alpha.2 entry.
Build: `npm run build` passes, 0 errors / 0 warnings, 65 pages.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Quick wins from the UX review. Single commit, no breaking changes to existing URLs. Audience badges Three pill-shaped tags styled in brand.css (operator / author / developer). Inserted at the top of every English page so a reader can tell at a glance whether a page is meant for them. Plain HTML inline span - no .md to .mdx renames. Cheatsheet (new page, /docs/general/cheatsheet/) Single ctrl-F'able list of every activator, rule, action, item property, catalog, and command. Each row links to the full reference for that entry. Sidebar reorg "General Features" -> "Authoring menus" "Advanced Features" -> "Techniques" New "Reference" group: cheatsheet + examples Same files, more discoverable grouping. Onboarding tracks on splash Three LinkCards above the marketing copy: server operator, menu author, addon developer. Lands the reader on the right starting page instead of the generic "Get started" tutorial. RST anchor sweep (73 broken refs) Pre-Starlight code-spanned anchors (`prop-slot`, `api-extractor`, `hocon-obj`, `logical-and`, etc.) now resolve to actual Starlight URLs. Both the inline-code form and bare bracket-link form were swept. Alpha API warning Aside / :::caution[Alpha API] block on every developer page. The 2.0 surface is still subject to change before stable. Inline examples (general/examples.md -> .mdx) Eight reference menu .conf files copied locally under src/examples/, imported with ?raw, rendered through Starlight's <Code> in collapsible <details>. Operators no longer have to bounce out to GitHub to read a sample. Multi-file casino and admin still link out. item-format progressive disclosure The 25-row master table got split into five focused tables grouped by purpose (slot/cooldown, material installers, display, mechanics, conditional). Mobile-friendly, easier to skim. Cheatsheet cross-link added at the top. Build: `npm run build` passes, 0 errors / 0 warnings, 67 pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous sweep replaced inline-code RST anchors with generic "See an [example](URL)" everywhere, including labels that weren't references at all (extractor type names, activator/rule names used prosaically inline). Reader complaint: every row of the activators table linked back to the same activators page. Right. Targeted fixes: activators.md - dropped the now-pointless "Example" column from the master table and made each rule name link to its in-page anchor (#activator-command, etc.). Restored the eight Extractor type lines to their actual labels (`extractor-cmd`, `extractor-region`, `extractor-item`, ...). Replaced "similar to [example]()" with a real cross-link to the section above. rules.md - rebuilt the master table with the Example column dropped and rule names linked to their anchors. Special rules link out to /docs/advanced/logical/. actions.md - dropped the Example column from the master table with a per-row Python pass. Fixed the two broken Data type cells (removeButton / removePlaced got "[example]" leaked into the type column from the sweep). Resolved the "similar to [example] item property" lines to specific item properties (potionData, bookData). generation.mdx - restored Extractor type labels. drag-and-drop.md - replaced the meaningless "See the [reference] placeholders" sentence with a clean cross-link to the `extractor-item` documentation. Second sweep pass picked up the bare-anchor markdown links my first map missed: value-extractors, hocon-list-str, prop-all, input-ctx-main, input-ctx-placeholder, input-prof-ex, logical-rules-list, input-how-to. Build: `npm run build` passes, 0 errors / 0 warnings, 67 pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Each action that has a dedicated section below the table is now a clickable name in the table - readers click "teleport" and jump to its section. Actions without a section (small one-liners like setHealth, setFoodLevel, pagePrev) stay plain since linking back to the same #all-actions anchor would be noise. Shared sections are linked too: broadcast and miniMessage point to #message; itemClear to #remove-item; resetSkin to #set-skin; the six set/inc/dec/mul/div variants of /var and /varp share #global-vars and #personal-vars respectively. placeItem also got the drag-and-drop cross-link in the description column for consistency with removeButton/removePlaced. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
abstractmenus.github.io/api/... isn't hosting the 2.0 javadocs (404).
Until that's back up, point readers at the source files in the
minecraft-plugin repo (and the hocon repo for ConfigNode /
NodeSerializer).
Two URL shapes:
abstractmenus.github.io/api/ru/abstractmenus/api/X.html
-> github.com/AbstractMenus/minecraft-plugin/blob/master/api/src/main/java/ru/abstractmenus/api/X.java
abstractmenus.github.io/api/ru/abstractmenus/hocon/api/X.html
-> github.com/AbstractMenus/hocon/blob/master/src/main/java/ru/abstractmenus/hocon/api/X.java
package-summary.html targets become repo /tree/ links to the directory.
20 links total across 6 developer pages. Verified all 17 minecraft-plugin
paths exist locally.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…conf out
The 2.0 provider model lets multiple economy / level / permission /
skin backends coexist on one server. Previously the actions table
just said "Vault required" for giveMoney / takeMoney - that's the
default but no longer the only option.
Provider selection
Added a "Provider selection" section to actions.md with worked
examples for the three call shapes:
- default backend (no provider field)
- per-action override (provider: "vault" | "playerpoints")
- server-wide default (config.conf providers.economy = ...)
Plus a resolution order box and a cross-link to the developer
page on writing your own provider.
Updated the actions table: every provider-backed entry
(giveMoney/takeMoney, givePermission/removePermission, addGroup/
removeGroup, giveLevel/takeLevel, giveXp/takeXp, setSkin/resetSkin)
now Type-column "Number or Object" since the {amount, provider}
shape is supported, and Description-column links to
#provider-selection.
rules.md money row updated similarly.
config.conf
Until now the config reference was buried as a section in
start/installation.mdx. Server operators searching for "config"
expect a dedicated page. Split into start/config.mdx with:
- full default config in one block
- per-section key tables (persistence, integrations, paths,
time, providers, click debounce)
- reload semantics — which keys take effect on /am reload vs
need a restart
installation.mdx links to it now instead of inlining.
Sidebar adds /docs/start/config/ between installation and how-to.
Cross-links in faq.mdx and item-format.md updated.
Build: npm run build passes, 0 errors / 0 warnings, 69 pages
(was 67; +config plus RU fallback).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brought the wiki back in sync with the plugin and api source on master. Developer API factual fixes: - handlers.md: PermissionsHandler / LevelHandler / PlaceholderHandler method tables corrected to actual interface methods (no more invented getGroup, hasLevels, etc.) - variables.md, migration.mdx: savePlayer -> savePersonal; documented getGlobal/getPersonal/deleteGlobal/deletePersonal and Var typed accessors - utils.md: dropped non-existent 3-arg PlaceholderHandler.replace; documented full BukkitTasks surface and Logger - serializers.md: replaced non-existent ConfigNode.children() with childrenList/childrenMap and the rest of the actual API Cheatsheet rewrite: - Actions and Catalogs sections were generated without sweep against the type registry. Replaced with the real registered names from CoreActionsBundle / CoreCatalogsBundle (no more giveItem, permGroups, takeLevels, etc.). Added missing item properties (data, attributeModifier, nameLight, loreLight) to the property table and noted the legacy nameLight/loreLight semantics. Coverage gaps (registered but undocumented): - general/actions.md: lpMetaSet / lpMetaRemove section, command ignorePlaceholder option, full customSound parameters - general/item-format.md: data, attributeModifier, nameLight, loreLight in the tables; new "Attribute modifier" section - advanced/generation.mdx: missing slice catalog, EntityCatalog world parameter - advanced/logical.md: playerScope wrapper section - general/commands.md: /var <time> / <replace> trailing arguments Anchor / link fixes: - item-format.md: aligned heading slugs with table links (#equipped-item, #flag, #potion-effect, #firework, #book, #banner, #nbt-tags); bindings link now points to menu-structure where the section actually lives - start/faq.mdx, start/how-to.mdx: replaced #prop-slot, #struct-bindings, #struct-auto-refresh with the real slugs (#slot, the bindings section in menu-structure, #auto-refresh) - general/actions.md: same #bindings -> menu-structure redirect - general/menu-structure.md: SHIFT_RIGHT description corrected from "Left" to "Right" GitBook-style placeholder links cleaned up: - Replaced [text](identifier) artifacts in actions, variables, placeholders, menu-structure, hocon, drag-and-drop, input, templates, generation with real targets or anchors - Removed the [example](...) placeholder text artifacts that survived migration Other: - start/installation.mdx: removed the non-existent animatedHead item property reference (animations come through %hanim_:..:..% placeholder, not a property) - advanced/drag-and-drop.md: example referenced slot 15 but the HOCON above used slot 6 - general/actions.md: removed "Vault by default" / "LuckPerms by default" wording that contradicted the auto-resolve behaviour documented in the same file Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Both locales now sit symmetrically under src/content/docs/:
src/content/docs/
en/ English content
ru/ Russian content (mirrors en/, fills in gradually)
Previously English lived at the root of content/docs/ via Starlight's
"root locale" pattern, with Russian as a sibling ru/ subdirectory.
That worked but read as visually asymmetric and made it less obvious
where new locales would slot in.
Changes:
- defaultLocale: "root" -> "en"
- locales config: dropped root, added explicit `en` entry
- Moved every English source file into src/content/docs/en/
- Updated all internal /docs/(start|general|advanced|developers|demo|
changelog)/ links to /docs/en/... in the English content
- feed.xml.ts now points at /docs/en/changelog/
- Added a / -> /docs/en/ redirect so bare /docs/ still works
- Sidebar Changelog link updated with per-locale translations
- Fixed relative imports in en/general/examples.mdx (one level deeper
now, "../../../examples" -> "../../../../examples")
- README updated: layout, URL scheme, page-creation flow
URLs change for everything except images and the RSS feed:
/docs/start/how-to/ -> /docs/en/start/how-to/
/docs/img/foo.png -> stays
/docs/feed.xml -> stays
Starlight hardcodes width: 6.25em on the theme picker <select>, which is
fine for English ("Auto/Dark/Light") but truncates Russian "Светлая" to
"Свет..." in the header. Override to width: auto with min-width: 6.25em
so the dropdown sizes to its widest option without shrinking below the
English layout.
Starlight has a TODO in their ThemeSelect.astro about this exact issue;
the upstream fix isn't there yet, so we patch it locally.
The markdownlint job on PR #2 surfaced a mix of real bugs in the carry-over RST content and overly strict rules that would force churn-only reformatting on dozens of reference tables. Real fixes: - rules.md: escape literal "||" inside the if-rule operator table cell; the unescaped pair was being parsed as two extra column delimiters, breaking the whole row. - 5 fenced code blocks tagged with `text` (terminal output / file tree examples that pandoc emitted without a language hint). - 4 admonition-then-heading transitions got the missing blank line. - "Math actions (personal)" disambiguates the duplicate of the global-vars heading. - input.mdx had two consecutive "## Activator context" headings; the second is renamed to "Context placeholders" to match its content. Rule relaxations in .markdownlint-cli2.jsonc: - MD060 (compact tables): RST conversion uses no-space-around-pipes. Reformatting every table is churn-only. - MD059 (descriptive link text): legacy "[here]" links live in many carry-over pages and will be addressed during the editorial pass. - MD036 (emphasis as heading): used for image captions in some pages. - MD030 (list marker space): RST emits "1. " with two spaces. - MD046 (code block style): both fenced and indented are valid Markdown. - MD024 (duplicate heading): switched to siblings_only so headings like "Set" can appear under both "Global vars" and "Personal vars".
The operator table in rules.md mixed three styles: bare cells with backslash-escaped angle brackets, bare cells with no escaping, and a few cells already in backticks. Normalised to backticks across the board so each operator and each example renders as monospace code. The "||" row remains the lone exception. Markdown's table parser splits rows on literal "|" before code spans are recognised, so any "||" inside backticks corrupts the cell count and breaks rendering. The escape "\\|\\|" outside backticks is the only construction the parser accepts. That row reads slightly differently (no monospace) but the table no longer breaks.
Mix of three things on the failing run: 1. Real typos in carry-over content - fixed: - Abstact / AbstactMenus / AbstrctMenus / AbstratMenus -> AbstractMenus - Unfortunatelly -> Unfortunately - futher -> further - independ -> independent / independently - palceholders, placehodlers -> placeholders - variabes -> variables - resctiction -> restriction - sometning -> something - invenotry -> inventory - owerwrite -> overwrite - wothout -> without - priproty -> priority - uderstandable -> understandable - begid -> begins - atleast -> at least - spefic -> specific - paraed -> parsed While there, rewrote a few of the surrounding sentences for clarity. 2. Russian content (src/content/docs/ru/**) ignored. cspell would need the Russian dictionary to evaluate it; not worth pulling in for the handful of translated pages we'll have. Russian content gets reviewed by humans during translation. 3. Project terms and common technical English added to the dictionary (.cspell-words.txt): Nanit, Nashorn, Deutsch, hanim, mrules, vart, varpt, itemstack, actionbar, classloader, Cheatsheet, Cooldown, Frontmatter, interactable, pickable, respawn, respawning, laggy, topo (as in topological sort), and the British-English spellings the project uses (behaviour, colour, recognised, customisation, organisation).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs site moves off Sphinx + sphinx-rtd-theme and onto Astro Starlight. Same URLs, same content for the most part, different engine underneath.
Why now
The old setup was painful to keep current. Adding a page meant writing reStructuredText, knowing which Sphinx directives apply, and running a Python toolchain. The theme had no dark mode, no localization story, and search felt slow. Several pages had drifted out of sync with the plugin and nobody was rushing to fix RST.
What's actually different
The engine is Astro Starlight on Markdown / MDX. Adding a page is dropping a
.mdfile undersrc/content/docs/. Components like Steps, Tabs, FileTree, and LinkCard are available where they help; plain Markdown still works for everything else.Light and dark themes ship by default, with a manual toggle and
prefers-color-schemerespected.Localization is wired up. English lives at the root, Russian at
/docs/ru/. One page is translated so the language switcher in the header has something to switch to. Pages without a Russian version fall back to English with a "translate this" notice.Pagefind handles search at build time. The site is built and deployed by GitHub Actions on every push to
main; the previously committed pre-builtdocs/folder is gone.The "Getting Started" tutorial, the developer integration guide, and the FAQ are rewritten to use the new components and to fix references that had gone stale. Other pages were brought over and cleaned up wherever conversion artifacts crept in (escaped angle brackets, leftover RST div blocks, empty-anchor links).
Reviewer notes
/docs/dev/...paths now live at/docs/developers/...because Starlight reservesdevfor its own routing.Follow-ups (not in this PR)