Ciro Santilli

Markdown Style Guide

Readable and portable Markdown style guide.

The source code is available on GitHub: https://github.com/cirosantilli/markdown-style-guide/

Use AsciiDoc

If:

consider using AsciiDoc instead of Markdown.

The Asciidoctor implementation is likely the best choice as of 2019.

AsciiDoc takes Markdown, and adds just enough to write serious books, while reducing some markdown annoyances at the same time.

Here is one example of what you can achieve on GitHub with a README.adoc: https://github.com/cirosantilli/linux-kernel-module-cheat/tree/v3.0#linux-kernel-module-cheat

And here is Buildroot’s perfect AsciiDoc-based generated documentation:

Advantages:

Disadvantages:

Wishlist:

If you already have a Markdown document and want to convert it to asciidoc, Pandoc is a good way to start. The conversion is not yet perfect, but it does go a long way. One good command is:

markdown-to-adoc() (
  # Markdown to asciidoc the way I like it.
  f="$1"
  shift
  pandoc --atx-headers --base-header-level 2 -o "${f%.*}.adoc" --wrap=none "$f" "$@"
)

GitHub upstream.

About

Considers original specification, CommonMark and other extensions.

This project is community driven, and tries to reach consensus. Maintainers will only step in if the community cannot reach a decision. Discussion will take place on the issue tracker.

A Chinese translation can be found at: http://einverne.github.io/markdown-style-guide/zh.html

Notable users

Are you notable? Send a pull request.

If you are a notable user:

You are more likely to be notable if your project:

Options system

Disputed points will be given multiple alternative style options.

Each feature and option will receive a lowercase hyphen separated identifier.

Each option will have a header of form:

# Option key:value

The first option header that appears in this text is the default value.

E.g., if line wrapping had 3 alternatives, we could give it the key wrap, and for each alternative create a header:

# Option wrap:space
# Option wrap:no
# Option wrap:sentence

When referring to this guide, specify all non-default options in a comma separated fashion:

Use the Markdown Style Guide wrap:space, code:indented

Design goals

Readability vs writability

Many design choices come down to:

There may be use cases in which either is preferred:

The current style is inconsistent with either of those optimizations. For now, we propose two sets of options (profiles) which optimize either one: readability and writability profiles.

Readability profile
Writability profile

Typographic conventions

When this style guide needs to represent multiple adjacent spaces, or spaces at the beginning or ending of code blocks, this will be mentioned explicitly in prose, and a dot will be used to make the space visible.

E.g.:

a, space, b:

a b

a, 2 spaces, b:

a..b

space, ab:

.ab

ab, space:

ab.

Alternatives

google/styleguide by Google.

carwin/markdown-styleguide. This guide was originally forked from it. It has been extended considerably, some decisions were modified, and no original lines remain.

http://tirania.org/blog/archive/2014/Sep-30.html by Miguel de Icaza (GNOME, Mono). Short.

https://github.com/slang800/markdown-styleguide

Lint tools

Asked on Stack Exchange: http://softwarerecs.stackexchange.com/questions/7138/markdown-lint-tool/

General rules

File

File extension

Use .md.

Rationale: why not .mkd or .markdown?

File name

Prefer to base the file name on the top-header level:

Good:

file-name.md

Bad, multiple consecutive hyphens:

file--name.md

Bad, surrounding hyphens:

-file-name-.md

Rationale: why not underscore or camel case? Hyphens are the most popular URL separator today, and markdown files are most often used in contexts where:

Whitespaces

Newlines

Don’t use 2 or more consecutive empty lines, that is, more than two consecutive newline characters, except where they must appear literally such as in code blocks.

End files with a newline character, and don’t leave empty lines at the end of the file.

Don’t use trailing whitespace unless it has a function such as indicating a line break.

Good:

- list
- list

# Header

Good, code block:

The markup language X requires you to use triple newlines to separate paragraphs:

    p1


    p2

Bad:

- list
- list


# Header

Rationale: multiple empty lines occupy more vertical screen space, and do not significantly improve readability.

Spaces after sentences

Option space-sentence:1

Use a single space after sentences.

Bad, 2 spaces:

First sentence.  Second sentence.

Good:

First sentence. Second sentence.

Rationale: advantages over space-sentence:2:

Advantages of space-sentence:2:

Option space-sentence:2

Bad, single space:

First sentence. Second sentence.

Good:

First sentence.  Second sentence.

Line wrapping

Option wrap:inner-sentence

Try to keep lines under 80 characters by breaking large paragraphs logically at points such as:

It is acceptable to have a line longer than 80 characters, but keep in mind that long sentences are less readable and look worse in tools such as git diff.

Set your editor to wrap lines visually for Markdown in case a large line is present.

Good:

This is a very very very very very very very very very very very very very long not wrapped sentence.
Second sentence of of the paragraph,
third sentence of a paragraph
and the fourth one.

Rationale:

Downsides:

Option wrap:no

Don’t wrap lines.

Rationale: very easy to edit. But diffs on huge lines are hard to read.

Option wrap:space

Always wrap at the end of the first word that exceeds 80 characters.

Rationale: source code becomes is very readable and text editors support it automatically. But diffs will look bad, and changing lines will be hard.

Option wrap:sentence

Rationale: similar advantages as wrap:inner-sentence, but easier for people to follow since the rule is simple: break after the period. But may produce long lines with hard to read diffs.

Notable occurrence: ProGit 2.

Code

Dollar signs in shell code

Don’t prefix shell code with dollar signs $ unless you will be showing the command output on the same code block.

If the goal is to clarify what the language is, do it on the preceding paragraph.

Rationale: harder to copy paste, noisier to read.

Good:

echo a
echo a > file

Bad:

$ echo a
$ echo a > file

Good, shows output:

$ echo a
a
$ echo a > file

Good, language specified on preceding paragraph:

Use the following Bash code:

echo a
echo a > file

What to mark as code

Use code blocks or inline code for:

Don’t mark as code:

Spelling and grammar

Use correct spelling and grammar.

Prefer writing in English, and in particular American English. Rationale: American English speakers have the largest GDP, specially in the computing industry.

Use markup like URL or code on words which you do not want to add to your dictionary so that spell checkers can ignore them automatically.

Beware of case sensitive spelling errors, in particular for project, brand names or abbreviations:

When in doubt, prefer the same abbreviation as used on Wikipedia.

Avoid informal contractions:

Block elements

Line breaks

Avoid line breaks, as they don’t have generally accepted semantic meaning.

In the rare case you absolutely need them, end a lines with exactly two spaces.

Headers

Option header:atx

Bad:

Header 1
========

Header 2
--------

### Header 3

Good:

# Header 1

## Header 2

### Header 3

Option header:setex

Bad:

# Header 1

## Header 2

### Header 3

Good:

Header 1
========

Header 2
--------

### Header 3

Top-level header

If you target HTML output, write your documents so that it will have one and only one h1 element as the first thing in it that serves as the title of the document. This is the HTML top-level header.

How this h1 is produced may vary depending on your exact technology stack: some stacks may generate it from metadata, for example Jekyll through the front-matter.

Storing the top-level header as metadata has the advantage that it can be reused elsewhere more easily, e.g. on a global index, but the downside of lower portability.

If your target stack does not generate the top-level header in another way, include it in your markdown file. E.g., GitHub.

Top-level headers on index-like files such as README.md or index.md should serve as a title for their parent directory.

Downsides of top-level headers:

Advantages of top-level headers:

Header case

End of a header

Indicate the end of a header’s content that is not followed by a new header by an horizontal rule:

# Header

Content

---

Outside header.

Header length

Keep headers as short as possible.

Instead of using a huge sentence, make the header a summary to the huge sentence, and write the huge sentence as the first paragraph beneath the header.

Rationale: if automatic IDs are generated by the implementation, it is:

Good:

# Huge header

Huge header that talks about a complex subject.

Bad:

# Huge header that talks about a complex subject

Punctuation at the end of headers

Don’t add a trailing colon : to headers.

Rationale: every header is an introduction to what is about to come next, which is exactly the function of the colon.

Don’t add a trailing period . to headers.

Rationale: every header consists of a single short sentence, so there is not need to add a sentence separator to it.

Good:

# How to do make omelet

Bad:

# How to do make omelet:

Bad:

# How to do make omelet.

Header synonyms

Headers serve as an index for users searching for keywords.

For this reason, you may want to give multiple keyword possibilities for a given header.

To do so, simply create a synonym header with empty content just before its main header.

E.g.:

# Purchase

# Buy

You give money and get something in return.

Every empty header with the same level as the following one is assumed to be a synonym. This is not the case if levels are different:

# Animals

## Dog

Blockquotes

Lists

Marker

Unordered
Option list-marker:hyphen

Use the hyphen marker.

Good:

- a
- b

Bad:

* a
* b
+ a
+ b

Rationale:

Downsides:

Option list-marker:asterisk

Use *.

Option list-marker:plus

Use +.

Ordered

Prefer lists only with the marker 1. for ordered lists, unless you intend to refer to items by their number in the same markdown file or externally.

Prefer unordered lists unless you intent to refer to items by their number.

Best, we will never refer to the items of this list by their number:

- a
- c
- b

Better, only 1.:

1. a
1. c
1. b

Worse, we will never refer to the items of this list by their number:

1. a
2. c
3. b

Acceptable, refer to them in the text:

The output of the `ls` command is of the form:

    drwx------  2 ciro ciro        4096 Jul  5  2013 dir0
    drwx------  4 ciro ciro        4096 Apr 27 08:00 dir1
    1           2

Where:

1. permissions
2. number of files directory contains

Acceptable, meant to be referred by number from outside of the markdown file:

Terms of use.

1. I will not do anything illegal.
2. I will not do anything that can harm the website.

Rationale:

Spaces before list marker

Do not add any space before list markers, except to obey the current level of indentation.

Bad:

  - a
  - b

Good:

- a
- b

Good, c is just following the indentation of b:

-   a
-   b
    - c

Bad, c modified the indentation of b:

-   a
-   b
      - c

Rationale:

Spaces after list marker

Option list-space:mixed

Bad, every item is one line long:

-   a
-   b

Good:

- a
- b

Bad, every item is one line long:

1.  a
1.  b

Good:

1. a
1. b

Bad: item is longer than one line:

- item that
  is wrapped

- item 2

Good:

-   item that
    is wrapped

-   item 2

Bad: item is longer than one line:

- a

  par

- b

Good:

-   a

    par

-   b
Option list-space:1

Always add one space to the list marker.

Bad, 3 spaces:

-   a

    b

-   c

Good:

- a

  b

- c

Bad, 2 spaces:

1.  a

    b

1.  c

Good:

1. a

   b

1. c
Rationale: list-space mixed vs 1

The advantages of list-space:1 are that

The disadvantages of list-space:1

Indentation of content inside lists

The indentation level of what comes inside list and of further list items must be the same as the first list item.

Bad:

-   item that
  is wrapped

-   item 2

Good:

-   item that
    is wrapped

-   item 2

Bad:

-   item 1

  Content 1

-   item 2

      Content 2

Good (if it matches your spaces after list marker style):

-   item 1

    Content 1

-   item 2

    Content 2

Bad:

- item 1

    Content 1

- item 2

    Content 2

Good (if it matches your spaces after list marker style):

- item 1

  Content 1

- item 2

  Content 2

Avoid starting a list item directly with indented code blocks because that is not consistently implemented. CommonMark states that a single space is assumed in that case:

-     code

  a

Empty lines inside lists

If every item of a list is a single line long, don’t add empty lines between items. Otherwise, add empty lines between every item.

Bad, single lines:

- item 1

- item 2

- item 3

Good:

- item 1
- item 2
- item 3

Bad, multiple lines:

-   item that
    is wrapped
-   item 2
-   item 3

Good:

-   item that
    is wrapped

-   item 2

-   item 3

Bad, multiple lines:

-   item 1

    Paragraph.

-   item 2
-   item 3

Good:

-   item 1.

    Paragraph.

-   item 2

-   item 3

Bad, multiple lines:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2
-   item 3

Good:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2

-   item 3

Rationale: it is hard to tell where multi-line list items start and end without empty lines.

Empty lines around lists

Surround lists by one empty line.

Bad:

Before.
- item
- item
After.

Good:

Before.

- list
- list

After.

Case of first letter of list item

Each list item has the same case as it would have if it were concatenated with the sentence that comes before the list.

Good:

I want to eat:

- apples
- bananas
- grapes

because it could be replaced with:

I want to eat apples
I want to eat bananas
I want to eat grapes

Good:

To ride a bike you have to:

- get on top of the bike. This step is easy.
- put your foot on the pedal.
- push the pedal. This is the most fun part.

because it could be replaced with:

To ride a bike you have to get on top of the bike. This step is easy.
To ride a bike you have to put your foot on the pedal.
To ride a bike you have to push the pedal. This is the most fun part.

Good:

# How to ride a bike

- Get on top of the bike.
- Put your feet on the pedal.
- Make the pedal turn.

because it could be replaced with:

# How to ride a bike

Get on top of the bike.
Put your feet on the pedal.
Push the pedal.

Punctuation at the end of list items

Punctuate at the end of list items if either it:

Otherwise, omit the punctuation if it would be a period.

Bad, single sentences:

- apple.
- banana.
- orange.

Good:

- apple
- banana
- orange

Idem:

- go to the market
- then buy some fruit
- finally eat the fruit

Good, not terminated by period but by other punctuation.

- go to the marked
- then buy fruit?
- of course!

Bad, multiple sentences:

- go to the market
- then buy some fruit. Bad for wallet
- finally eat the fruit. Good for tummy

Good:

- go to the market
- then buy some fruit. Bad for wallet.
- finally eat the fruit. Good for tummy.

Note: nothing forbids one list item from ending in period while another in the same list does not.

Bad, multiple paragraphs:

-   go to the market

-   then buy some fruit

    Bad for wallet

-   finally eat the fruit

    Good for tummy

Good:

-   go to the market

-   then buy some fruit.

    Bad for wallet.

-   finally eat the fruit.

    Good for tummy.

Bad, starts with upper case:

- Go to the market
- Then buy some fruit
- Finally eat the fruit

Good:

- Go to the market.
- Then buy some fruit.
- Finally eat the fruit.

Definition lists

Avoid the definition list extension since it is not present in many implementations nor in CommonMark.

Instead, use either:

Code blocks

Option code:fenced

Only use fenced code blocks.

Comparison to indented code blocks:

Don’t indent fenced code blocks.

Always specify the language of the code is applicable.

Good:

```ruby
a = 1
```

Bad:

```
a = 1
```

Option code:indented

Only use indented code blocks.

Indent indented code blocks with 4 spaces.


Code blocks must be surrounded by one empty line.

Prefer to end the phrase before a code block with a colon :.

Good:

Use this code to blow up your PC:

    sudo rm -rf /

Bad, no colon

Use this code to blow up your PC

    sudo rm -rf /

Horizontal rules

Don’t use horizontal rules except to indicate the End of a header.

Rationale:

Use 3 hyphens without spaces:

---

Tables

Extension.

Good table:

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

Rationale:

Separate consecutive elements

Separate consecutive:

with an empty HTML comment <!-- -->.

- list 1
- list 1

<!-- -->

- list 2
- list 2
    code 1
    code 1

<!-- -->

    code 2
    code 2
> blockquote 1
> blockquote 1

<!-- -->

> blockquote 2
> blockquote 2
- list
- list

<!-- -->

    code outside list
    code outside list

Span elements

Don’t use inner spaces.

Good:

**bold**
`code`
[link](http://a.com)
[text][name]

Bad:

** bold **
` code `
[ link ]( http://a.com )
[text] [name]

For inline code in which the space is crucial:

Good:

Use the hyphen marker followed by one space `- a`  for unordered lists.

Rationale: most browsers don’t render the surrounding spaces nor add them to the clipboard on copy.

Links:

Definitions:

Good:

[id2]:     http://long-url.com
[long id]: http://a.com        "name 1"

Bad, not ordered by id:

[b]: http://a.com
[a]: http://b.com

Bad, not aligned:

[id]: http://id.com
[long id]: http://long-id.com

Single or double quote titles

Use double quotes, not single quotes.

Rationale: single quotes do not work in all major implementations, double quotes do.

Emphasis

Bold

Use double asterisk format: **bold**.

Rationale: more common and readable than the double underline __bold__ form.

Italic

Use single asterisk format: *italic*.

Rationale:

Uppercase for emphasis

Don’t use uppercase for emphasis: use emphasis constructs like bold or italic instead.

Rationale: CSS has text-transform:uppercase which can easily achieve the same effect consistently across the entire website if you really want uppercase letters.

Emphasis vs headers

Don’t use emphasis elements (bold or italics) to introduce a multi line named section: use headers instead.

Rationale: that is exactly the semantic meaning of headers, and not necessarily that of emphasis elements. As a consequence, many implementations add useful behaviors to headers and not to emphasis elements, such as automatic id to make it easier to refer to the header later on.

Good:

# How to make omelets

Break an egg.

...

# How to bake bread

Open the flour sack.

...

Bad:

**How to make omelets:**

Break an egg.

...

**How to bake bread:**

Open the flour sack.

...

All automatic links must start with the string http.

In particular, don’t use relative automatic links. Use bracket links instead for that purpose.

Good:

[file.html](file.html)

Bad:

<file.html>

Good:

<https://github.com>

Bad:

<github.com>

Rationale: it is hard to differentiate automatic links from HTML tags. What if you want a relative link to a file called script?

Don’t use email autolinks <address@example.com>. Use raw HTML instead.

Rationale: the original markdown specification states it:

“performs a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots”.

Therefore, the output is random, ugly, and as the spec itself mentions:

but an address published in this way will probably eventually start receiving spam