feat(site): rebuild the index site on the xpkgindex framework — fixes #170 - #176
Merged
Conversation
Everything mcpp-specific about how this index is presented now lives in `.xpkgindex/plugins/mcpp.py` rather than being assumed by the generator. - identity: `namespace.name`, which is what `mcpp add` accepts — closes #170, and gives the three `imgui` packages three pages instead of one - classifies packages by how they are consumed (`import` / `#include` / tool), the axis a C++ user actually browses by; `categories` is set by no descriptor in this repo - reads the `mcpp = {}` block (both its table and string forms) and merges `mcpp.deps`, which the site never showed for the 21 packages that use it - Form A packages resolve their module name from the upstream manifest: the `export module` declaration in the lib target's interface unit is the authority (libxpkg's `[targets.xpkg]` exports `mcpplibs.xpkg`, not `xpkg`), falling back to the manifest description and then to this repo's own tests. Never derived from the package name — godot-cpp-m is named `godot-cpp-m` and imported as `godot_cpp` - links each package to the test project that demonstrates it, so package pages show code CI compiles rather than a snippet written for the website - `.xpkgindex/interfaces.json` carries the handful of lines no rule can reach (abseil, bzip2, xz …), each taken from this repo's own tests Upstream lookups are cached in `.xpkgindex/cache/` and committed, so a normal deploy touches no network; `refresh-site-cache.yml` refreshes them on demand.
Six commands from nothing to a project that imports a library from this index: install mcpp, create and run a project, `mcpp add nlohmann.json`, import it, run again — then links onward, to the packaging guides here and to mcpp's own docs. Every command is taken from mcpp's README and this repo's own test projects rather than written from memory, and the page is the site's Docs landing (and the homepage card), so the flow a newcomer sees is the one CI exercises.
Site title and lede, the install labels, the quick-start card, the doc nav titles, and everything the plugin writes — the 'how you use it' axis, the Usage/Build/Features headings, the '✓ example' and 'CN mirror' badges, the notes explaining where a module name came from — now carry en / zh / zh-Hant. Identifiers stay untranslated on purpose: 'import', '#include', 'modules', 'targets' are what you type or what mcpp.toml calls the field, and a reader comparing the page against a manifest needs the same word in both. Also points the new website icon at https://mcpp.d2learn.org.
deploy-site and refresh-site-cache both checked out at the default depth of 1. xpkgindex detects a shallow clone and skips the growth curve, the history line and the contributor list rather than replaying a truncated log — so the deployed site has quietly been missing all three. fetch-depth: 0 restores them. Both now also pass GITHUB_TOKEN, which raises the API rate limit and enables the author -> login mapping that merges one person's several git identities. deploy-site's path filter gained .xpkgindex/** and docs/**: the plugin decides how every package reads, the docs are rendered as site pages, and the cache is what an offline build renders from. A change to any of them changes the site as much as a descriptor does, and none of them triggered a deploy. site-check is new. validate.yml proves the packages compile; this proves they still render — offline, so a pull request spends no rate limit and the result depends only on what is in the repository, and --strict, so a replayed history that disagrees with the tree fails rather than warns. It also fails on any warning at all, because a warning nobody reads becomes permanent, and asserts that the pages a reader actually lands on exist in all three locales.
Sunrisepeak
force-pushed
the
site/framework-v2
branch
from
August 7, 2026 00:39
0a64449 to
2019bc8
Compare
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.
Adopts the rebuilt xpkgindex framework (openxlings/xpkgindex#3) and adds the mcpp plugin that teaches it what a package means here.
Fixes #170.
The bug in #170, and the larger one behind it
The site advertised
mcpp add json@3.12.0. The client rejects that — mcpp resolvesnlohmann.json, namespace included. The same generator also gave every package a page at/packages/<short-name>.html, so three differentimguipackages resolved to one URL and two of them silently disappeared.Both are the same mistake: treating one name as three different things. The framework now keeps
display,slugandinstall_refas separate fields that are never derived from one another, and a duplicate slug fails the build naming both descriptors. This repo's plugin opts intoIdentity.joined, which is what makes the install command correct here — and is exactly what xim-pkgindex must not do.What the plugin adds
import,#include, a tool binary, or an upstream-providedmcpp.toml. That axis comes from themcpp = {}extension block and is what a C++ user actually browses by.mcpp = {}into build blocks: modules, targets, language,import_std, sources, features, generated files.export moduledeclaration, or from this repo's own test project that imports it — and where neither exists it shows a mutedimport …;rather than inventing an identifier. Six packages whose module name cannot be derived at all are curated by hand in.xpkgindex/interfaces.json, each line taken from a real test.enrich_remote), which is whymcpp.toml-shaped packages now show real build information instead of "not fetched"..xpkgindex/cache/github.jsonis committed: the deploy build reads it and touches no network, so a rendered page never depends on GitHub being reachable at deploy time.refresh-site-cacheis how new data gets in.Site
Three locales (
en/zh/zh-Hant), including everything this repo supplies — title, install labels, the quick-start card, doc names, and the plugin's own facet axes, block titles and badges. Identifiers stay untranslated:import,#include,modules,targetsare what you type or whatmcpp.tomlcalls the field.A quick start in both languages (
docs/quick-start.md,docs/zh/quick-start.md) is the landing document and the homepage card. Every command in it was checked against this repo's README and its tests.CI
fetch-depth: 0restores them. Both now passGITHUB_TOKENas well..xpkgindex/**anddocs/**are now in the path filter; a plugin or doc change used to deploy nothing.validate.ymlproves the packages compile; this proves they still render. Offline, so a PR spends no rate limit;--strict, so a replayed history that disagrees with the tree fails rather than warns; fails on any warning; and asserts the pages a reader lands on exist in all three locales.Locally: 81 packages, 16 namespaces, 119 versions, 8 contributors, 0 warnings,
--offline --strictgreen.