A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file verify-doc-structure.mjs
* @brief Enforce the site's one structural rule.
*
* A page's directory path is its sidebar path is its URL. That rule is what
* makes a URL say where a page lives, and it only holds while three things
* agree: the sidebar in `astro.config.mjs`, the files on disk, and the two
* locales. Nothing else notices when they drift — Astro fails on a sidebar entry
* naming a page that does not exist, but a page in no sidebar group builds
* happily and is reachable only by search, and an English page with no Chinese
* translation silently serves English to a Chinese reader.
*
* Run from `docs/astro/`, before or after the build — it reads source, not dist:
*
* node scripts/verify-doc-structure.mjs
*/
import { readFileSync, readdirSync, existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join, relative, sep } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const ROOT = join(here, '..');
const DOCS = join(ROOT, 'src', 'content', 'docs');
const CONFIG = join(ROOT, 'astro.config.mjs');
/** Generated by TypeDoc, and not ours to organise. */
const GENERATED = 'api-ts';
/** The splash page, which is the site root rather than a sidebar entry. */
const ROOT_PAGE = 'index';
/** Every .mdx under `dir`, as slugs relative to it. */
function pages(dir) {
const out = [];
const walk = (d) => {
for (const e of readdirSync(d, { withFileTypes: true })) {
const p = join(d, e.name);
if (e.isDirectory()) {
if (e.name !== GENERATED && e.name !== 'zh-cn') walk(p);
} else if (e.name.endsWith('.mdx')) {
out.push(relative(dir, p).split(sep).join('/').replace(/\.mdx$/, ''));
}
}
};
walk(dir);
return out;
}
const config = readFileSync(CONFIG, 'utf8');
const slugs = [...config.matchAll(/slug: '([a-z0-9/-]+)'/g)].map((m) => m[1]);
const problems = [];
// The sidebar names pages that exist, in both locales.
for (const slug of slugs) {
for (const [label, prefix] of [['English', ''], ['Chinese', 'zh-cn/']]) {
if (!existsSync(join(DOCS, `${prefix}${slug}.mdx`))) {
problems.push(`the sidebar lists "${slug}", which has no ${label} page`);
}
}
}
// Every page is somewhere in the sidebar. A page reachable only by search is a
// page nobody browsing the manual will find.
const seen = new Set(slugs);
for (const p of pages(DOCS)) {
if (p !== ROOT_PAGE && !seen.has(p)) problems.push(`page "${p}" is in no sidebar group`);
}
// A group's general page is `<dir>/overview` and is labelled Overview — the
// group header already says the topic. (Its `title` stays descriptive.)
for (const m of config.matchAll(/\{ label: '([^']+)',[^}]*slug: '([a-z0-9/-]+\/overview)'/g)) {
if (m[1] !== 'Overview') problems.push(`"${m[2]}" is labelled "${m[1]}" in the sidebar, not Overview`);
}
// The locales are mirrors: same tree, same names.
const en = new Set(pages(DOCS));
const zh = new Set(pages(join(DOCS, 'zh-cn')));
for (const p of en) if (!zh.has(p)) problems.push(`no Chinese page for "${p}"`);
for (const p of zh) if (!en.has(p)) problems.push(`no English page for "${p}"`);
if (problems.length) {
console.error(`doc structure: ${problems.length} problem(s)`);
for (const p of problems) console.error(` ${p}`);
console.error('\n The rule: a page\'s directory path is its sidebar path is its URL (docs/SITE.md).');
process.exit(1);
}
console.log(`doc structure: ${en.size} pages × 2 locales — sidebar, filesystem and translations agree.`);