TopolearnThese few rules cover most of what you type in READMEs, issues and chat.
Markdown is plain text that stays readable as is and converts to HTML.
Paragraphs are runs of lines separated by one or more blank lines. A single newline inside a paragraph does not start a new line in the output: the lines are joined, so you can wrap long text in your editor freely.
To force a line break inside a paragraph, end the line with a backslash \ or with two or more spaces. The backslash is better because trailing spaces are invisible and editors often strip them. (GitHub comments and some chat apps treat every newline as a break, but files rendered by CommonMark don't.)
Inline formatting:
*italic*or_italic_for emphasis;**bold**or__bold__for strong emphasis;***both***;- backticks for
inline code, shown in a monospace font with no formatting inside.
Prefer * for emphasis inside words: un*frigging*believable works, while underscores inside words are ignored, so snake_case_name stays intact.
To show a character that would otherwise format text, escape it with a backslash: \*not italic\*. Any ASCII punctuation character can be escaped this way.
Example
This is the first paragraph. These two lines
are joined into one line in the output.
This is a second paragraph, after a blank line.\
This line starts after a hard break (trailing backslash).
Some *italic*, some **bold**, some ***bold italic***,
and some `inline_code()`.
snake_case_stays_as_is, but un*believ*able works.
\*literal asterisks\*
<!-- renders to:
<p>This is the first paragraph. These two lines
are joined into one line in the output.</p>
<p>This is a second paragraph, after a blank line.<br />
This line starts after a hard break (trailing backslash).</p>
... -->Remember
- Blank lines separate paragraphs; single newlines are joined
- End a line with \ (or two spaces) for a hard line break
- em, strong,
code; escape punctuation with a backslash
Watch out for
- Expecting a single newline to start a new line in a rendered README.