docs: fix reference sidebar ordering and group the subsystem pages

The VitePress config declared no position for the subsystem or other-interface
sections, so `indexOf` returned -1 and sorted them ahead of every declared
group: the reference landing page's own sidebar entry sat 1549px below the
fold. Four subsystem pages also shared `order` values with pages in the same
section, resolved only by sort stability and array concatenation order.

Section placement and collapse move into the manifest as a per-locale
declaration, and `sectionSpec` throws for an undeclared section instead of
sorting it silently to the top. Subsystem pages are grouped by concern, the
six topical groups collapse until one holds the page being read, and page
order derives from array position.

The projector drops the language-switcher line and repository badge the
canonical pages carry for their GitHub readers. The navigation bar gains the
DeepSeek wordmark, a release-stage tag, and a favicon; the sidebar scrollbar
rests invisible and appears while scrolling. Subsystem pages carry a two-level
outline, and the two plugin-development tracks now cross-link.
This commit is contained in:
Yichen Jiang
2026-08-12 13:52:27 +08:00
parent 15c84cdc4b
commit 0a2ac90617
18 changed files with 477 additions and 117 deletions
+32 -1
View File
@@ -292,6 +292,37 @@ export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage,
return `---\n${fields}\n---\n\n${markdown}`
}
/** The switcher line a canonical page carries so its GitHub reader can reach the other language. */
const LANGUAGE_SWITCHER = /^(?:English \| \[中文\]\([^)]*\)|\[English\]\([^)]*\) \| 中文)$/
/** The repository badge a canonical page carries for its GitHub reader. */
const REPOSITORY_BADGE = /^\[!\[[^\]]*\]\(https:\/\/img\.shields\.io\/[^)]*\)\]\([^)]*\)$/
/**
* Drop the lines that address a canonical page's GitHub reader.
*
* The site carries a locale switcher in its navigation bar and links the
* repository from every page, so projecting these lines would repeat both — the
* switcher as the first element under each heading.
*
* @param markdown Rewritten canonical Markdown content.
* @returns The content without the switcher line or the repository badge.
*/
function withoutRepositoryChrome(markdown: string): string {
const lines = markdown.split('\n')
const switcher = lines.findIndex(line => LANGUAGE_SWITCHER.test(line))
// Only the switcher introducing the page qualifies; further down the same
// text is prose or a sample rather than the page's own header.
if (switcher !== -1 && switcher < 8) {
lines.splice(switcher, lines[switcher + 1] === '' ? 2 : 1)
}
const badge = lines.findLastIndex(line => REPOSITORY_BADGE.test(line))
if (badge !== -1) {
lines.splice(lines[badge - 1] === '' ? badge - 1 : badge, lines[badge - 1] === '' ? 2 : 1)
}
return lines.join('\n')
}
/**
* Select the Markdown rendered for one published page.
*
@@ -300,7 +331,7 @@ export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage,
* @returns Full Markdown for ordinary pages or frontmatter-only Markdown for a locale home page.
*/
export function projectedPageContent(markdown: string, page: DocsPage): string {
if (page.sidebar !== null) return markdown
if (page.sidebar !== null) return withoutRepositoryChrome(markdown)
if (!markdown.startsWith('---\n')) {
throw new Error(`project-doc-site: locale home source ${JSON.stringify(page.source)} must start with YAML frontmatter.`)
}