Improve documentation visuals for web rendering#7
Merged
Merged
Conversation
Replace fragile ASCII-style documentation visuals with reusable HTML/CSS components across the token context, MCP cost, savings curve, and agent loop sections. Align the zh-TW and English pages so the rendered site stays consistent and the step cards read cleanly in the browser. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Doc visuals switch ASCII → semantic HTML + shared CSS components, fix browser rendering drift (esp zh-TW proportional fonts). Adds reusable token-context-diagram + guide-visual layouts, then rewires multiple pages to use them.
Changes:
- Add
token-context-diagram+guide-visualcomponent styles indocs/stylesheets/extra.css. - Replace ASCII diagrams with HTML structure in EN pages (context window, MCP tool cost multiplication, savings/risk curve, Agent Mode loop).
- Add matching zh-TW HTML visuals for same sections.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 16 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/stylesheets/extra.css | Add shared CSS for new HTML visual components + responsive behavior. |
| docs/01-why-tokens-matter.md | Replace context window ASCII diagram with token-context-diagram HTML. |
| docs/01-why-tokens-matter.zh-TW.md | Same replacement for zh-TW page. |
| docs/08-mcp-tool-costs.md | Replace multiplication ASCII block with guide-visual formula/cards layout. |
| docs/08-mcp-tool-costs.zh-TW.md | Same replacement for zh-TW page. |
| docs/09-comparisons-data.md | Replace diminishing-returns ASCII chart with guide-visual curve bars. |
| docs/09-comparisons-data.zh-TW.md | Same replacement for zh-TW page. |
| docs/10-practical-setup.md | Replace Agent Mode loop ASCII block with guide-visual step cards. |
| docs/10-practical-setup.zh-TW.md | Same replacement for zh-TW page. |
| │ └──────────────────┘ └─────────────────────┘ │ | ||
| └─────────────────────────────────────────────────┘ | ||
| ``` | ||
| <div class="token-context-diagram" role="img" aria-label="Context window containing input tokens and output tokens"> |
| │ └──────────────────┘ └─────────────────────┘ │ | ||
| └─────────────────────────────────────────────────┘ | ||
| ``` | ||
| <div class="token-context-diagram" role="img" aria-label="Context window containing input tokens and output tokens"> |
|
|
||
| 10,000 tokens × 15 steps = 150,000 tokens just for tool definitions. | ||
| ``` | ||
| <div class="guide-visual" role="img" aria-label="Tool definition cost multiplies across servers, tools, and agent steps"> |
| Agent mode 走 15 steps： | ||
| 10,000 × 15 = 150,000 tokens | ||
| ``` | ||
| <div class="guide-visual" role="img" aria-label="工具定義成本會隨 server、tool 與 agent 步數相乘"> |
| Token Savings → | ||
| lite full ultra extreme | ||
| ``` | ||
| <div class="guide-visual" role="img" aria-label="Compression savings versus quality risk curve"> |
| </section> | ||
| <section class="guide-visual__card"> | ||
| <h4>Heavy setup example</h4> | ||
| <p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p> |
| <h4>Heavy setup example</h4> | ||
| <p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p> | ||
| <div class="guide-visual__flow"> | ||
| <p class="guide-visual__math">10,000 tokens x 15 steps</p> |
| <div class="guide-visual__grid guide-visual__grid--2"> | ||
| <section class="guide-visual__card"> | ||
| <h4>公式</h4> | ||
| <p class="guide-visual__math">Tools loaded = servers x tools_per_server x tokens_per_tool</p> |
| </section> | ||
| <section class="guide-visual__card"> | ||
| <h4>重度設定範例</h4> | ||
| <p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p> |
| <h4>重度設定範例</h4> | ||
| <p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p> | ||
| <div class="guide-visual__flow"> | ||
| <p class="guide-visual__math">10,000 tokens x 15 steps</p> |
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
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.
Why
Several documentation diagrams rendered acceptably in Markdown source but broke down on the published site, especially in zh-TW pages where proportional fonts and mixed-width text made ASCII layouts drift out of alignment. This updates those visuals so the browser rendering is stable and easier to review.
What changed
guide-visualstyles for card, formula, curve, and step-flow layouts so the site can render these sections consistently without relying on monospaced box drawing.Notes for reviewers
mkdocs servewas intermittently stale during iteration on Windows.