Wiki-ready docs: SVG diagrams, prose descriptions, accessible formatting

[taylorarndt]

Summary

Taylor made the wicky branch to experiment with getting the workshop docs wiki-ready. This PR captures everything that happened — what we tried, what failed, what worked, and why. The branch name is wicky because it was a wiki experiment playground.

Branch to review: https://github.com/Community-Access/git-going-with-github/tree/wicky

---

What This PR Does

1. ASCII art diagrams replaced with SVG images (7 diagrams)

Every ASCII art diagram that used box-drawing characters or tree structures is now an SVG image rendered with monospace text on a dark background. Each image is followed by a "Description" heading and a full prose text description so screen reader users always know there is a readable explanation below the image.

Files with diagram changes:

• docs/01-understanding-github-web-structure.md — repository page layout (box art)
• docs/02-navigating-repositories.md — repository page layout (box-drawing chars)
• docs/03-the-learning-room.md — learning room shared repo tree
• docs/12-github-pull-requests-extension.md — PR extension panel tree
• docs/15-issue-templates.md — template folder structure tree
• docs/appendix-m-vscode-accessibility-reference.md — accessible diff viewer tree
• docs/appendix-q-github-actions-workflows.md — workflow folder tree

Pattern in every file:

![](images/diagram-name.svg)

### Description

Full prose description of what the diagram shows...

2. Tables converted to prose (appendix-i-github-projects.md)

Four data tables were converted to bold-term prose format because they rendered poorly on the wiki and were harder to scan with a screen reader:

• v1 vs v2 comparison table → bold key, inline comparison
• Field Types table → bold type name, description sentence
• Built-in Workflows table → bold workflow name, what-it-does sentence
• Filter Syntax table → inline code + description sentence

The project status example table (with real columnar data) was deliberately kept as a table because it represents actual tabular data.

3. Box-drawing characters cleaned up in code blocks

Files that had box-drawing characters or arrows inside code blocks were cleaned up to use ASCII equivalents so they render consistently everywhere. This affects:

• docs/04-working-with-issues.md
• docs/05-working-with-pull-requests.md
• docs/06-merge-conflicts.md
• docs/07-culture-etiquette.md
• docs/14-accessible-code-review.md

4. README repository tree replaced

The large ASCII tree in the README that mapped the entire repo structure was replaced with a cleaner version using ASCII-safe characters instead of box-drawing characters.

5. GitHub Actions workflow for wiki sync

Added .github/workflows/sync-docs-to-wiki.yml — automatically syncs docs/ to the GitHub Wiki whenever docs change on the main branch.

6. SVG generation script

Added scripts/generate-diagram-svgs.py — a Python script that generates all 7 SVG diagram images. Uses monospace font on a dark background (#161b22) with light text (#e6edf3) and rounded corners. Can be re-run anytime the diagrams need updating.

---

The Journey — What We Tried and Why

This was not a straight path. Here is the full story of what happened, what I tried, and what decisions were made along the way.

Attempt 1: Raw ASCII art on the wiki

The original docs had ASCII art using box-drawing characters inside code blocks. On the main GitHub repo these render fine. But on the GitHub Wiki, pipe characters inside code blocks were being parsed as markdown table cells, breaking the layout completely. The box-drawing characters also looked inconsistent across different font stacks.

Result: Diagrams looked broken on the wiki. Kept working in the main repo.

Attempt 2: Replace box-drawing chars with ASCII

Replaced all box-drawing characters with plain ASCII (+, -, |). This fixed the character rendering issue but the pipe problem on the wiki persisted — GitHub Wiki parses pipe as table syntax even inside fenced code blocks.

Result: Still broken on wiki. Slightly better but fundamentally the same problem.

Attempt 3: Mermaid diagrams

Converted all 7 diagrams to Mermaid code blocks. Mermaid renders as SVG on GitHub, so no text-parsing issues. Added accTitle and accDescr properties to each Mermaid block for accessibility.

What happened: Mermaid rendered as opaque SVG images. Screen readers could not navigate the nodes — the entire diagram was a single image element. The accTitle and accDescr metadata was actually making things worse — the screen reader would read the accessibility metadata as noise before hitting the diagram, but the diagram itself was still completely opaque. It was the worst of both worlds: extra text to wade through, then an unreadable image.

Result: Mermaid is NOT accessible for screen reader users despite having accessibility metadata. Abandoned.

Attempt 4: Mermaid with prose descriptions, no accessibility metadata

Kept Mermaid diagrams but removed accTitle/accDescr. Added full prose text descriptions above each diagram so screen readers would read the text and sighted users would see the Mermaid SVG.

What happened: The prose descriptions were good, but the Mermaid diagrams themselves were not reliably showing the textual diagram content — they rendered differently across contexts, and the screen reader experience was still poor because the Mermaid SVG was just noise after the description.

Result: Descriptions worked great. Mermaid did not.

Attempt 5: Back to original ASCII art + prose descriptions

Pulled the original ASCII art from main branch and restored all 7 diagrams in code blocks, keeping the prose descriptions above them.

What happened: The ASCII art looked correct in the repo, but still had rendering issues on the wiki (the original problem). And visually it was not clean.

Attempt 6 (Final): SVG images + prose descriptions + Description heading

The final solution that stuck:

1. Generated SVG images from the ASCII art content using a Python script. The SVGs use monospace font on a dark background — they look like code blocks but render as images, so no text-parsing issues anywhere.

2. Image first, description below. Sighted users see the diagram immediately, then screen reader users find the description by heading navigation.

3. No alt text on images. Since the full prose description is right below each image under a "Description" heading, alt text would be redundant and create double-reading for screen reader users. The image uses empty alt and the description heading serves as the accessible alternative.

4. "Description" heading at the correct nesting level so screen reader users can press H to jump to it and know a text description follows every diagram.

---

Formatting Decisions

Throughout the process, several formatting preferences were established:

• No bullet lists, numbered lists, or dashed lists for descriptive content — screen readers read list markup ("list of 5 items, item 1, item 2...") which adds overhead. Prose flows better.
• No tables for simple key-value data — tables with only 2-3 columns of short text are better as bold-term prose (e.g., "Feature: description"). Tables are kept only for genuinely tabular data (the project status example).
• Inline sentences over lists for short enumerations (e.g., repo tabs).
• Tables kept for real tabular data — settings references, keyboard shortcuts, and multi-column data that genuinely needs column alignment.

---

Files Changed (23 total)

Category	Files
New: SVG diagrams	7 files in docs/images/
New: Generation script	scripts/generate-diagram-svgs.py
New: Wiki sync workflow	.github/workflows/sync-docs-to-wiki.yml
Diagram files	docs/01-*, docs/02-*, docs/03-*, docs/12-*, docs/15-*, appendix-m-*, appendix-q-*
Table-to-prose	docs/appendix-i-github-projects.md
Box-drawing cleanup	docs/04-*, docs/05-*, docs/06-*, docs/07-*, docs/14-*
Repo tree cleanup	README.md

---

Commit History

cd6f2bd Convert ASCII art diagrams to Mermaid and markdown tables for wiki rendering
f8b41c7 Add accessible titles, descriptions, and text alternatives to all Mermaid diagrams
dd70cf1 Convert layout diagrams in docs 01 and 02 to accessible Mermaid with text descriptions
d90e240 Fix pipe characters in code fences that break wiki rendering
147648e Change repo tabs to a proper list
f6d25fe Repo tabs as inline sentence instead of list
e489f12 Diagrams: plain text descriptions with clean Mermaid, tables to prose
7b147b5 Restore original ASCII art diagrams with text descriptions
b1b5f3a Convert ASCII art diagrams to SVG images
1ef152f Diagrams: image first, description below, no alt text
43f97b9 Add Description heading below each diagram image

You can see the full journey in the commits — Mermaid in, Mermaid out, ASCII back, SVGs final.

---

Wiki Status

The wiki has been manually synced throughout development. Once this merges, the GitHub Action at .github/workflows/sync-docs-to-wiki.yml will auto-sync docs/ to the wiki on every push to main.

---

How to Review

1. Browse the wicky branch on GitHub to see all changes rendered
2. Check the wiki at https://github.com/Community-Access/git-going-with-github/wiki to see how diagrams currently render
3. Verify SVG images display correctly in the 7 diagram files
4. Verify "Description" headings appear below each image
5. Verify tables in appendix-i are now prose format (except the project status example)

@accesswatch

[taylorarndt]

@accesswatch making pr because of huge changes.

[Copilot]

Pull request overview

This PR makes the workshop documentation “wiki-ready” by replacing fragile ASCII diagrams with generated SVG images plus prose descriptions, and by refactoring some table/list-heavy sections for more consistent rendering and accessibility across GitHub and the GitHub Wiki.

Changes:

• Add a Python generator that renders a set of ASCII-based diagrams into SVGs under docs/images/.
• Replace several in-doc ASCII diagrams with embedded SVG images and add “Description” sections beneath them.
• Convert selected tabular/key-value content into prose-style formatting and adjust some code-block formatting to avoid problematic characters on the wiki.

Reviewed changes

Copilot reviewed 12 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
scripts/generate-diagram-svgs.py	Adds the generator used to produce diagram SVGs in docs/images/.
docs/images/workflow-folder-tree.svg	New generated diagram image for workflow folder structure.
docs/images/template-folder-tree.svg	New generated diagram image for issue template folder structure.
docs/images/repo-page-layout-02.svg	New generated diagram image for repository page layout (variant 2).
docs/images/repo-page-layout-01.svg	New generated diagram image for repository page layout (variant 1).
docs/images/pr-tree.svg	New generated diagram image for PR extension panel tree.
docs/images/learning-room-tree.svg	New generated diagram image for the Learning Room PR tree concept.
docs/images/diff-viewer-tree.svg	New generated diagram image for VS Code accessible diff viewer structure.
docs/appendix-q-github-actions-workflows.md	Replaces an inline ASCII diagram with an SVG + prose description.
docs/appendix-m-vscode-accessibility-reference.md	Replaces an inline ASCII diagram with an SVG + prose description.
docs/appendix-i-github-projects.md	Converts multiple simple tables into prose/bold-term format; keeps truly tabular data as a table.
docs/15-issue-templates.md	Replaces an inline ASCII folder tree with an SVG + prose description; adjusts a “table” example format.
docs/14-accessible-code-review.md	Adjusts code-block instructions to avoid problematic glyphs/characters and improve clarity.
docs/12-github-pull-requests-extension.md	Replaces an inline ASCII tree with an SVG + prose description.
docs/06-merge-conflicts.md	Reworks examples to avoid wiki-hostile characters in code blocks; updates merge-conflict snippets.
docs/04-working-with-issues.md	Replaces arrow/pipe-heavy ASCII formatting inside code blocks with ASCII-safe equivalents.
docs/03-the-learning-room.md	Replaces an inline ASCII tree with an SVG + prose description; refactors sections into table/list formats.
docs/02-navigating-repositories.md	Replaces an inline ASCII layout diagram with an SVG + prose description.
docs/01-understanding-github-web-structure.md	Converts a repository-tabs code-block snippet into prose and replaces a large ASCII layout diagram with SVG + prose description.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This script executes file generation at import time. Other Python utilities in the repo use an if __name__ == "__main__": entrypoint; adding the same pattern here would make it safer to import/reuse generate_svg without side effects and more consistent with existing scripts.

Suggested change

	out_dir = os.path.join(os.path.dirname(__file__), "..", "docs", "images")
	os.makedirs(out_dir, exist_ok=True)
	for name, lines in diagrams.items():
	svg = generate_svg(lines)
	path = os.path.join(out_dir, f"{name}.svg")
	with open(path, "w", encoding="utf-8") as f:
	f.write(svg)
	print(f"Created {path}")
	print(f"\nDone: {len(diagrams)} SVGs generated.")
	def main():
	out_dir = os.path.join(os.path.dirname(__file__), "..", "docs", "images")
	os.makedirs(out_dir, exist_ok=True)
	for name, lines in diagrams.items():
	svg = generate_svg(lines)
	path = os.path.join(out_dir, f"{name}.svg")
	with open(path, "w", encoding="utf-8") as f:
	f.write(svg)
	print(f"Created {path}")
	print(f"\nDone: {len(diagrams)} SVGs generated.")
	if __name__ == "__main__":
	main()

[Copilot]

The PR description states a preference to avoid bullet lists for descriptive content due to screen reader overhead, but this section reintroduces a bullet list for the “Attention Items”. If the goal is consistent wiki/screen-reader-friendly formatting, consider converting these bullets into short prose sentences (or a bold-term format) like the other table-to-prose conversions in this PR.

[Copilot]

The PR description states a preference to avoid bullet lists for descriptive content, but this “folder structure” section is presented as a nested bullet list. If list markup is causing wiki/screen-reader friction, consider switching to a prose/bold-term format (one item per paragraph) or another non-list structure that still preserves hierarchy.

[Copilot]

The VS Code merge-conflict example shows ======= original as the diff3 “original” marker, but Git’s diff3 conflict format uses a ||||||| original line (and ======= is already the standard separator). This example is likely to confuse readers and doesn’t match actual conflict output; consider replacing with an accurate marker (or a non-marker label like ORIGINAL (diff3) if you need to avoid | characters).

Suggested change

	======= original -- (3-way merge, if enabled)
	||||||| original -- (3-way merge, if enabled)

[Copilot]

This section still says “Create a table:” but the example no longer forms a table (pipes were replaced with --). Either update the instruction to reflect the new format, or provide a wiki-safe table representation so learners can copy/paste an actual table.

[Copilot]

int(max_len * CHAR_W + 2 * PAD_X) truncates fractional pixels; with some fonts/browsers this can clip the last character(s) at the right edge. Consider using math.ceil(...) (and similarly for height if needed) to guarantee enough space for the rendered text.