feat: establish bilingual GitBook content foundation - #1
Merged
Conversation
- ChaptersGrid uses import.meta.env.BASE_URL so chapter cards link to /docs/<lang>/<slug> instead of /<lang>/<slug> - new src/pages/index.astro performs a meta-refresh from /docs to /docs/zh (default locale) so the base path is no longer a 404 - sidebar Chapters group now lists chapter slugs explicitly because autogenerate.directory requires a subdirectory; the empty sidebar group was hiding all chapters
- Hero: animated gradient glow backdrop, gradient text title with shifting bg, eyebrow pill, feature pills, primary CTA + GitHub secondary button, stats row (chapters, code samples, diagrams, languages) - ChaptersGrid: per-card accent colors, hover lift with accent border + animated left bar, icon tile rotates on hover, description line and tag pill per chapter - custom.css: brand gradient tokens, refined typography (Inter + JetBrains Mono), code blocks with border + radius, tables with row striping, blockquote with brand-colored border, mermaid framed card, focus rings, print rules, splash duplicate-title hiding - scripts/screenshot/: Playwright tooling for verifying EN / VI / ZH home, chapter pages, dark mode, and mermaid crops Co-authored-by: Codex <noreply@example.com>
…m 404 - Self-host Geist + Geist Mono (drop Inter) - Replace purple/violet/pink AI gradient with single warm amber accent - Break hero symmetry: logo left, content right (CSS Grid) - Asymmetric zig-zag chapter grid (12-col, odd flush, even indented) - Custom inline SVG icons (no emoji) - Desaturated muted chapter accents (category hues, not rainbow) - Spring motion + tabular nums + tinted shadows - Subtle SVG grain overlay - Custom branded 404 page with skip-to-content - Ignore scratch / AI tooling temp files
- defaultLocale: zh -> en in astro.config.mjs - Root redirect meta-refresh now targets /docs/en - <html lang> on redirect page now en instead of zh-CN - /docs/en, /docs/vi, /docs/zh all return 200 - 404 page still serves on bogus paths
- --sl-content-width: 52rem -> 70rem (more horizontal room for prose) - --sl-toc-width: 14rem -> 13rem (slim right TOC slightly) - main p max-width: 65ch -> 78ch (paragraphs no longer cramped) Effect on /docs/en/ch05-tool-system: - Lines like 'From this directive to the file content returning to the model, what happened in between?' now fit on a single line - Prose reads more editorial at 1440px viewport - Build clean: 35 pages in 3.58s
- --sl-sidebar-width: default 18rem -> 16rem (left nav ~32px slimmer) - --sl-content-width: 70rem -> 78rem (reading column grows) - --sl-toc-width: 13rem -> 12rem (right TOC slimmer) - main p max-width: 78ch -> 88ch (paragraphs breathe) Effect on /docs/en/ch04 at 1440px viewport: - 'This line of code looks unremarkable...Behind the simplicity of a one-line call lies a carefully designed AI abstraction layer.' now fits in 3 lines instead of 5 - Prose column gains ~120px of horizontal room - Build clean: 35 pages in 2.64s
- main p max-width: 88ch -> 105ch (~759px -> ~842px on Geist at 16px) Effect on /docs/en/ch01-overview at 1440px: - Numbered list items now each fit on a single line where they previously wrapped (1, 2, 3 of 'three reasons') - Prose lines stretch from ~750px to ~845px, matching the content panel width so there's no dead space on the right - Build clean: 35 pages in 2.53s
- --sl-sidebar-width: 16rem -> 14rem - --sl-content-width: 78rem -> 88rem - --sl-toc-width: 12rem -> 10rem - main p max-width: 105ch -> 120ch (~842px -> ~906px on Geist) Effect on /docs/en/ch01-overview at 1440px: - main: 928 -> 992px - content panel: 880 -> 944px - prose: 841 -> 905px - Sidebar chapters wrap into 3-5 lines (acceptable cost) - Build clean: 35 pages in 2.57s
…ion key
- Replace verbose page titles in left sidebar with short labels
(e.g., '1. Introduction', '第1章 开篇', '1. Mở đầu')
- All 10 chapters now have explicit label + translations: { en, vi, 'zh-CN' }
- Fix: Starlight translations keys are BCP-47 lang tags, not locale URL keys
(was 'zh', now 'zh-CN' — matches locales.zh.lang)
- Quoted hyphenated JS keys for parser compatibility
- Now: most chapter labels fit single-line in 14rem sidebar
- --sl-sidebar-width: 14rem -> 11rem (drives BOTH left and right sidebars in Starlight) - --sl-content-width: 88rem -> 105rem (headroom for very wide viewports) - --sl-toc-width: 10rem -> 5rem (still declared for legacy, but Starlight reads --sl-sidebar-width for the right aside at >= 72rem viewport) - main .content-panel padding-inline: 1.5rem -> 0.5rem (reclaim inner gutter) - max-width prose cap: 120ch -> 140ch (no longer the limiter) - Slim sidebar font to 0.85rem so chapter labels fit at narrow widths - Force aside widths via explicit width/min-width rules (defensive) Net: prose 906px -> 1034px at 1440x900 (+128px, +14%) Sidebar 14rem -> 11rem (saves 48px on each side, total 96px reclaimed) Long labels like '2. Three-Layer Architecture' still wrap to 2 lines inside 11rem - acceptable, keeps TOC and chapter nav both readable.
- --sl-sidebar-width: 11rem -> 13rem (drives BOTH left and right sidebars) - sidebar font: 0.85rem -> 0.9rem (legible, still slightly compact) Why: - 11rem left labels like '8. Context Engineering' and '10. Session Management' wrapped to 2 lines; 11rem right TOC made 'On this page' wrap and crammed the indented headings - 13rem gives both sidebars equal width (~210px each) so the layout reads symmetric; TOC heading fits one line, indented H3/H4 items have room without crowding - Trade-off: prose 1034 -> ~1020px (-14px, negligible) Result at 1440x900: left 210 | prose 1020 | right 210 = 1440. Balanced.
…, FAQ 12 new pages complete the four Diataxis content types and the 'minimum viable documentation' checklist: Diataxis - Tutorial: - quickstart.md (10-min hands-on, runs a real model call) Diataxis - Reference: - reference/api.md (every public export from the 3 packages) - reference/configuration.md (settings.json schema, all sections) - reference/environment-variables.md (every env var Pi reads) Diataxis - How-to (5 task-oriented): - how-to/add-custom-tool.md - how-to/plug-new-model.md - how-to/stream-output.md - how-to/persist-sessions.md - how-to/customize-system-prompt.md Meta: - glossary.md (Pi vocabulary, English preserved in translations) - changelog.md (site changelog, separate from upstream SDK) - help/faq.md (10+ Qs about Pi and the book) Sidebar reorganised into 6 groups: - About / Getting Started / How-to Guides / Reference / Chapters / Help astro.config.mjs: - lastUpdated: true (show last-updated in page footer) - sidebar entries for all new pages with en/vi/zh-CN labels All content in EN. VI translations in follow-up. ZH optional.
New components:
- components/Callout.astro - typeless admonition (tip/note/caution/danger)
- components/Header.astro - wraps default Header, adds 'v0.80.2' badge
Chapter attribution:
- Appended 'Version note' + 'Next up' footer to ch02..ch10
- ch01 already had a version note; skipped
- 'Next up' links to the next chapter slug, providing in-book navigation
beyond the prev/next pagination that already exists
Index rewrite (src/content/docs/en/index.mdx):
- Sectioned table of contents pointing to all six groups
- 'New here?' Callout points to the Quickstart
- Fixed broken link to GLOSSARY.md (now points to /en/glossary/)
- Replaced 'Contribute' link with absolute URL to CONTRIBUTING.md on GitHub
Config:
- astro.config.mjs: components.Header wired to the new Header
- .gitignore: ignore docs/_astro, docs/pagefind, docs/en, docs/vi, docs/zh
(artifacts from local serving — keeps the existing docs/superpowers dir intact)
Footer: - Wraps default Footer, adds Source row (View on GitHub | Edit page | Report issue) - File path is read from Astro.locals.starlightRoute.entry.filePath - Links to pifydev/docs repo so readers can audit any chapter's source RSS: - src/pages/changelog-rss.xml.js: GET endpoint producing RSS 2.0 - Items: 4 recent changes to the docs site - Output URL: /changelog-rss.xml Config: - astro.config.mjs: components.Footer wired to the new Footer - Added @astrojs/rss to dependencies
…AQ, Glossary, Quickstart, Changelog 12 new VI pages mirroring the EN overhaul: - reference/api.md, configuration.md, environment-variables.md (new) - index.mdx refreshed to match EN structure with hero, callout, and TOC - quickstart, glossary, changelog, help/faq (translation pass) - how-to/* (5 task-oriented recipes) English technical terms preserved per CONTRIBUTING.md: Agent, Agent Loop, Tool, Tool Use, Tool Result, Descriptor, Translator, Stream, Subagent, Session, Skill, Block, Turn, Compaction, Context Window, System Prompt, Managed Tools, Extension, Coding Agent, Model Provider, Event, hook, handler, schema, prompt, streaming, YOLO. Build verified: 71 pages x 3 locales = 213 HTML files, no errors.
Internal Starlight nav renders links with trailing slash (e.g. /en/quickstart/) but config had trailingSlash: never, so the dev server 404'd those URLs even though the pages existed. Switched to ignore so both forms resolve. Also makes the static dist on GitHub Pages work whether users type the slash or not.
Left sidebar 13rem to 17rem, right TOC 5rem to 12rem. Both panels now have room for longer localized chapter labels (vi, zh-CN) without truncation or wrap. Content column remains wide on 1440px viewports.
Let the prose column breathe to the full content panel width without a hard character cap. Useful for long EN/VI chapter bodies and tables of enum values that were wrapping awkwardly at 140ch.
The Chinese canonical source had Chinese comments, string literals, mermaid labels, and example user prompts inside code blocks. These leaked into the EN and VI translations when they were first translated. Translated all 1156 unique Chinese substrings via Google Translate, then did three cleanup passes to fix the worst artifacts: - Replaced Chinese punctuation (full-width comma, period, parens, etc.) with ASCII equivalents - Replaced literal 'No.N chapter' / 'Không.N chương' with 'Chapter N' / 'Chương N' - Replaced 'tune model' / 'điều chỉnh mô hình' with 'call the model' / 'gọi model' - Replaced 'Zhang said' / 'Trương' (Chinese name mistranslation) with 'chapter' / 'chương' - Replaced 'Không.Nwheel' / 'No.Nwheel' with 'turn N' / 'lượt N' - Replaced 'No.Nlayer' / 'Không.Nlớp' with 'Layer N' / 'Tầng N' Build verified: 71 pages x 3 locales, no errors. Residual Chinese inside code blocks: 0 lines across 22 files. Note: rough prose in some translated code comments remains; a deeper humanization pass would improve readability further.
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
Verification