docs: EN as root locale, SEO metadata, branding, footer, and prose in the API reference - #35
Merged
Merged
Conversation
…e in the API reference Same treatment as rasuvaeff/yii3-mcp's docs site, adapted for property-testing's existing EN/RU bilingual structure (73 pages per language). EN as root locale - Moved docs/en/** to docs/** (English served at '/', no redirect hop) — docs/index.md was a JS meta-refresh redirect to /en/; it's now the real home page. Russian keeps its 'ru/' subdirectory and URL prefix, unchanged. - Every internal link, the sidebar/nav config, aggregate.mjs, generate-api.mjs and check-integrity.mjs updated for the new path scheme. SEO - Unique per-page title/description on all 146 pages (73 per language): the 16 README-section-derived pages get it via a new `description` field in section-map.json (rendered by aggregate.mjs — editing the generated .md directly would be overwritten on the next build); the 3 direct-imports (roadmap/migrating/llms) get language-specific text (RU's is a pointer-page note, since those sources have no RU sibling); the 12 truly hand-authored pages got it directly; the 84 generated API pages get it from each class's docblock summary (see below). - Per-page canonical + Open Graph/Twitter meta via transformHead; sitemap.xml (built-in VitePress option, 146 URLs); robots.txt. Branding - Real logo assets (mark + full wordmark with the Testo-plugin badge) wired into the navbar, hero image (mark only, to avoid duplicating the hero's own text), and favicon. - Custom .vitepress/theme (Layout.vue + Footer.vue) adds a multi-column, locale-aware footer (nav labels and link prefixes switch on the current page's language via useData()), matching the pattern on php-testo.github.io. API reference - reflect-api.php now parses each class's and method's docblock (summary + @param descriptions) instead of discarding it. generate-api.mjs renders the summary as prose and every method as a fenced ```php signature block (multi-line for long parameter lists) with its documented parameters below — on both locales, since PHPDoc prose is English-only and translating it per-release isn't sustainable; the RU pages carry a one-line disclaimer instead of silently mixing languages. Fixes found while building this (both were verified live via google-chrome --headless screenshots before/after, Claude in Chrome having been declined this session) - check-anchors.mjs (new, ported from yii3-mcp): two wrong #fragment anchors (CounterExample linked to a nonexistent /api/index#counterexample instead of its own class page) in both intro/concepts.md and its RU mirror; extended to also verify, post-build, that every internal href carries the site's base prefix. - Footer.vue: VPSidebar is `position: fixed` with a z-index above static content for the entire page height, so an in-flow footer painted BEHIND it once scrolled that far — gave the footer `position: relative` + a higher z-index. Grid uses `repeat(auto-fit, minmax(160px, 1fr))` instead of fixed `fr` columns, which cannot overflow its container at any width.
Same treatment as yii3-mcp: default VitePress light mode keeps the page canvas and cards at almost the same near-white, so nothing visibly separates from the page. Scoped to :root:not(.dark) only — dark mode is untouched, and this works purely through VitePress's own CSS custom properties so it can never fight Shiki's light/dark token-color pairing. Brand accent (teal) untouched.
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.
Summary
Ports the same treatment applied to rasuvaeff/yii3-mcp's docs site to
property-testing's existing bilingual (EN/RU) VitePress site.
docs/en/**moved todocs/**— English is nowserved at
/, no more JS meta-refresh redirect hop. RU is unchanged(
ru/subdirectory + prefix). Every internal link, sidebar/nav config,and the three build scripts (
aggregate.mjs,generate-api.mjs,check-integrity.mjs) updated for the new path scheme.languages) — README-section pages via a new
descriptionfield insection-map.json(the generated.mdcan't be hand-edited, it'srebuilt every run), direct-imports (roadmap/migrating/llms) with
language-specific text, hand-authored pages directly, and the 84
generated API pages from each class's docblock summary. Per-page
canonical + OG/Twitter via
transformHead,sitemap.xml(146 URLs),robots.txt.badge) in navbar/hero/favicon. Custom
.vitepress/themeadds amulti-column, locale-aware footer — labels and link prefixes switch
on the current page's language via
useData().reflect-api.phpnow parses docblocks (summary +@param) instead of discarding them;generate-api.mjsrenders classsummaries as prose and methods as fenced ```php blocks. Shown on both
locales (PHPDoc is English-only and translating it per-release isn't
sustainable) — RU pages carry a one-line disclaimer instead of silently
mixing languages.
Bugs found and fixed while building this
#fragmentanchors (CounterExamplelinked to a nonexistent/api/index#counterexampleinstead of its own class page) inintro/concepts.mdand its RU mirror — caught by the newcheck-anchors.mjs(ported from yii3-mcp), which also verifies everyinternal
hrefin the built HTML carries the site's base prefix.VPSidebar(position: fixed, abovestatic content in the paint order for the whole page height) — fixed
with
position: relative+ a higher z-index. Its grid used barefrtracks (don't shrink below content min-width) — replaced with
repeat(auto-fit, minmax(160px, 1fr)).Test plan
npm run docs:build— aggregate → API generation → integrity check →VitePress build → anchor check, all green
146/146pages have adescription:frontmatter (verified by script)google-chrome --headless --screenshot(Claude in Chrome was declined this session): EN home at
/with noredirect, logo in navbar/hero, footer on both EN and RU pages (fully
visible, not hidden behind the sidebar, correct locale labels/links),
<head>tags (title/description/canonical/favicon) on EN and RUpages,
sitemap.xmlwith exactly 146 URLs