docs: restore 175 image figcaptions from GitBook migration#37
Merged
rachaelrenk merged 6 commits intomainfrom May 8, 2026
Merged
docs: restore 175 image figcaptions from GitBook migration#37rachaelrenk merged 6 commits intomainfrom
rachaelrenk merged 6 commits intomainfrom
Conversation
Add <figure>+<figcaption> wrappers to 175 images across 68 MDX files, restoring the visible captions that were lost during the GitBook → Astro Starlight migration. Captions extracted from the GitBook source and matched by image filename. Also adds: - CSS styling for figure and figcaption elements (centered, sm text, gray-3 color) in custom.css - Migration scripts (migrate-figcaptions.py for analysis, apply-figcaptions.py for automated application) Empty figcaptions (145 instances) are intentionally skipped — they had no visible text in GitBook either. Co-Authored-By: Oz <oz-agent@warp.dev>
…captions # Conflicts: # src/content/docs/agent-platform/capabilities/mcp.mdx
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
These were used to generate the content changes in this PR and don't need to live in the repo. Co-Authored-By: Oz <oz-agent@warp.dev>
Add an 'Image caption guidelines' section to AGENTS.md with rules for writing good figcaptions: orient don't instruct, keep short, no marketing language, don't repeat prose, don't list everything. Includes positive and negative examples. Also adds a brief editorial note in custom.css next to the figcaption styles pointing to the AGENTS.md guidelines. Co-Authored-By: Oz <oz-agent@warp.dev>
Apply the caption guidelines from AGENTS.md to all 174 figcaptions:
- Remove procedural instructions from captions (belongs in body text)
- Remove marketing language ('easily,' 'at a glance,' etc.)
- Shorten exhaustive lists to concise subject descriptions
- Trim verbose captions to ~10 words
- Add missing trailing periods for consistency
- Fix 'Oz Web App' casing to 'Oz web app' per terminology
140 captions rewritten across 58 files.
Co-Authored-By: Oz <oz-agent@warp.dev>
Rewrite 28 cryptic fragment captions (e.g. 'Derived from rules.', 'Alt-screen padding setting.') as complete sentences that orient the reader without requiring them to look at the image. Also adds 'Write complete sentences' as an explicit rule in the AGENTS.md image caption guidelines. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
approved these changes
May 8, 2026
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
2 participants
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
Restore image figcaptions lost in the GitBook to Astro Starlight migration, define caption quality standards in the style guide, and rewrite all captions to meet those standards.
Changes
Caption guidelines (new)
AGENTS.mdsrc/styles/custom.cssFigcaption restoration
src/styles/custom.css<figure>and<figcaption>elements: centered layout,var(--sl-text-sm)font,var(--sl-color-gray-3)color.src/content/docs/**/*.mdx(68 files)<figure>+<figcaption>with caption text extracted from the GitBook source, matched by image filename using a one-time migration script (not committed).Caption quality rewrites
src/content/docs/**/*.mdx(58 files)Scope
<figcaption>tags with no textContext
Part of the docs v2 bug bash follow-up work. Tracks to Notion item: Migration FF: image captions.
Co-Authored-By: Oz oz-agent@warp.dev