Markdown and documentation guide

Use ASCII art in a GitHub README

In a GitHub README, put ASCII art in a fenced code block to preserve its lines and spaces. If the drawing already contains consecutive backticks, choose a longer fence. Always include a readable plain-text heading or description.

Add a drawing to a README

Write the project name and description in ordinary text.
Add a blank line, then a line containing three backticks ```.
Paste the drawing without removing its spaces; close the block with three backticks on a separate line.
Preview the README before saving and check it in a narrow window.

GitHub’s code block documentation describes fenced blocks and optional syntax highlighting. For ASCII art, a block without a language label avoids unnecessary colours. You do not need HTML tags around every line.

The drawing should accompany useful information. Keep the name, purpose and installation instructions readable without having to decipher a decorative banner.

Case 1 — A README with a 7-column cat

This complete example can go into a README.md file. The drawing is 3 lines tall and at most 7 columns wide. The title and descriptive sentence remain outside the block.

# Workshop

A small welcome cat.

```
 /\_/\
( o.o )
 > ^ <
```

Self-contained README example: title, description and drawing in a fenced block.

Expected result: a “Workshop” heading, a descriptive sentence and a block containing the cat’s three lines. The two lines of three backticks are not displayed as content. The drawing’s _ and > characters do not trigger text formatting.

Inspecting the drawing alone gives 21 code points including its two line breaks, without a final line break. For a more regular border check, also try the 8-column box in the main guide.

Case 2 — The content already contains three backticks

A fence that is too short can close the block in the wrong place. Here the content must preserve two lines of three backticks, so the outer delimiters use four.

````
Example with an internal fence:
```
OK
```
````

The outer lines use four backticks. Both lines of three backticks belong to the displayed content.

Expected result: one block showing the four inner lines, including both visible ``` lines. The block does not end after the introductory sentence. This mechanism is defined in the GitHub Flavored Markdown specification.

A reliable rule for an automatic copy action

Find the longest consecutive run of backticks in the content. Choose a fence of at least three characters that is longer than that run. No internal run therefore needs three; three inside need four outside; four inside need five outside.

max_run = longest_consecutive_backtick_run(drawing)
fence = "`" * max(3, max_run + 1)
markdown = fence + "\n" + drawing + "\n" + fence

Pseudocode: the fence depends on the content. ArtASCII’s diagnostic uses this logic when copying for GitHub.

Both fences must start on their own line. Keep the outer delimiters needed by Markdown separate from the characters you actually want people to see.

Choose a FIGlet banner, text drawing or image

Need	Suggested format	What to watch
Decorative name for a command-line tool	Banner from the text generator.	Keep an accessible plain-text title nearby; avoid very wide banners.
Small animal or welcome decoration	Short ASCII cat in a block.	Do not let decoration push important instructions out of sight.
A diagram or architecture people need to understand	Structured explanation and a representation suited to the subject.	A decorative drawing cannot replace an explanation of relationships.
Converted photo or very wide composition	PNG with alternative text.	An image preserves the arrangement, but its characters are no longer copyable.
Example intended for editing	Code block and, where useful, a companion TXT file.	Preserve encoding and spaces when editing.

A FIGlet banner uses a font whose large letters are assembled from smaller characters; see the official FIGlet manual. Check font credits and terms when redistributing font files.

Check a misaligned design

Paste your text (maximum 100,000 characters)

Local analysis: your text stays in your browser. Unicode width counts code points, not actual display columns.

Checks before publication

Spaces and tabs

Preserve leading spaces. Automatic whitespace cleanup can remove meaningful spaces. Prefer ordinary spaces to tabs and check the source file when something shifts.

Invisible characters and width

Pasting can introduce a non-breaking space or an invisible character. The diagnostic reports their presence without predicting their effect in every renderer. Character count is a useful width guide for strict ASCII; Unicode, emoji and combining accents still need a visual check.

HTML and special characters

Inside a Markdown code block, keep the drawing’s original characters, including < and &. If you display them in your own HTML, use a <pre> element and escape the content correctly. Copying presentation HTML instead of the actual drawing creates a different input.

A GitHub README versus a GitHub Pages site

A README rendered on GitHub and a page generated by your theme are different contexts. On GitHub Pages, also inspect the site’s font, whitespace and overflow styles. The W3C CSS Text specification explains preserved spaces and line breaking.

Accessibility, limitations and reuse

Describe the drawing in a sentence if it carries information. If you choose PNG, write alternative text that explains its role rather than a long list of characters. A large banner should not be the only readable form of the project name.

These examples are complete control strings. Their syntax follows GitHub documentation and its Markdown specification; rendering in every theme, extension, terminal or application is not certified. The diagnostic is not an accessibility audit and does not measure pixels.

To continue, compare the templates, review ASCII versus Unicode, or read the specific Discord procedure. Do not assume every destination implements the same formatting rules.