ASCII Art in Documentation and READMEs

Using ASCII Art in Project Documentation

ASCII art in README files and documentation helps illustrate architecture, workflows, and interfaces without requiring external image hosting or rendering engines.

Markdown Code Blocks

Always wrap ASCII art in fenced code blocks to preserve spacing:

```
+--------+     +--------+     +--------+
| Client | --> | Server | --> |  DB    |
+--------+     +--------+     +--------+
```

Without code blocks, Markdown renderers will collapse whitespace and break the art. Use triple backticks (```) without a language identifier to prevent syntax highlighting from altering colors.

Architecture Diagrams

ASCII architecture diagrams are valuable because they:

• Live with the code — No external image files to manage
• Diff cleanly — Changes show up in pull request reviews
• Render everywhere — GitHub, GitLab, Bitbucket, plain text viewers

                    ┌─────────────┐
                    │   Gateway   │
                    └─────┬───────┘
                          │
              ┌────────┴────────┐
              │                 │
        ┌─────┴─────┐  ┌────┴─────┐
        │  Auth API  │  │  Data API  │
        └─────┬─────┘  └────┬─────┘
              │                 │
        ┌─────┴─────┐  ┌────┴─────┐
        │  User DB   │  │  Main DB   │
        └───────────┘  └───────────┘

Table of Contents with ASCII

src/
├── components/
│   ├── layout/
│   │   ├── Header.tsx
│   │   └── Footer.tsx
│   └── tools/
│       └── ImageToAscii.tsx
├── data/
│   └── tools.ts
└── lib/
    └── utils.ts

Accessibility Considerations

When using ASCII art in documentation:

1. Provide alt text — Describe what the diagram shows for screen reader users
2. Use HTML comments — Add <!-- Description: Architecture showing... --> before diagrams
3. Keep it supplementary — Always describe the diagram in surrounding text so the information is accessible without seeing the art
4. Consider Mermaid.js — For interactive documentation, Mermaid diagrams render as accessible SVGs while using a text-based syntax

Rendering Consistency

Test your ASCII art in:

• GitHub Markdown — The most common rendering environment for README files
• GitLab Markdown — Slightly different rendering than GitHub
• npm package pages — Uses GitHub README but may have different styles
• Documentation sites — Docusaurus, VitePress, MkDocs all render code blocks differently

When to Use Images Instead

If the diagram is complex (more than ~20 lines), consider using a generated SVG from a tool like Mermaid.js, PlantUML, or D2. These are stored as text files that diff cleanly but render as proper graphics.