Skip to content

Markdown Guidelines

Sean Kelly edited this page Jun 26, 2024 · 3 revisions

Markdown is a basic markup language with the goals of making text easy to write but also easy to read as simple plain text. But this same plain text can also be formatted nicely into HTML. It's similar and simpler than reStructuredText.

In addition to the The Markdown Guide and GitHub's Mastering Markdown, here are some extra notes to help make your Markdown shine, whether for wiki pages like this one, GitHub issue templates, project READMEs, and so forth.

Inline vs Block Markup

In markup languages (and in English in general) there's the notion of inline markup versus block markup. Inline markup is like these words that are suddenly in boldface, or inline HTML tags like <span> and <strong>.

Whereas block markup is the fact that these are two paragraphs (two blocks), or block HTML tags like <div> and <h2>.

When writing in Markdown, you can preserve the semantic differences between inline and block markup by using the formatting appropriate to each. For example, do this ✅

## Describe the Bug

A clear and concise description of what the bug is.

Don't do this ❌

**Describe the Bug**

A clear and concise description of what the bug is.

The former uses an actual heading block element, while the latter abuses an inline boldface element.

Why do this? One tangible benefit is for accessibility: screen-readers use semantic structure to better present information for people with disabilities. For example, a screen reader can speak boldface text in an emphatic voice while keyboard shortcuts allow those with motor difficulties to navigate between headings. Using boldface as a heading defeats both of these assistive technologies.

😮 Emoji

Modern operating systems let you type emoji directly into your files and even at your terminal prompts.

For macOS users, press Space and choose (or type a few characters to search) for the emoji or other character you want. Or choose "Emoji & Symbols" from the "Edit" menu of most apps.

For Windows users, press the Windows key and the period . or semicolon ; keys and then choose an emoji.

For various flavors of Linux, it … varies 😅. You can try right-clicking to get a context menu and choose "Insert Emoji" or try pressing ctrl and the period key.