Guides for SE student projects »

Markdown coding standard

  • The term 'markdown' in this document refers to GitHub Flavored Markdown.

  • Follow the syntax as strictly as specified here.

    RATIONALE: Minor deviations from the markdown syntax are sometimes forgiven by GitHub markdown rendering but may not be forgiven by GitHub Pages html rendering.

  • Do not wrap lines at a specific length. Coding standards for other languages typically specify a maximum length for a statement. However, Markdown is used to write natural language content which should not be chopped into a sentence fragments.

    RATIONALE: Doing so could throw off grammar checkers, and make it harder to modify content later (because a simple change might require re-sizing many adjacent lines).

  • Add a blank line at the beginning of a list.

Good
Here is a list:

* item 1
* item 2
Bad   
Here is a list:
* item 1
* item 2

  • Add a blank line at the beginning of a code block.

  • Add a space at the start of a heading.

Good
# Heading
Bad   
#Heading
  • Use blank lines to separate headings
Good
## Heading

Content of the paragraph.
Bad   
## Heading
Content of the paragraph.
  • Use blockquote symbol in every line of the blockquote.
Good
> first line
> second line
Bad   
> first line
  second line

  • Use generic numbering for ordered lists. i.e., use 1. for every item in an ordered list can make it easy to insert more items later. Generic numbers are converted to the correct numbers by GitHub markdown renderer.

    RATIONALE: If you use generic numbers, you can insert items into the middle of the list without modifying any existing items.

Good
1. item 1
1. item 2
1. item 3
Bad   
1. item 1
2. item 2
3. item 3

  • Use * for bullet-points (not -).

    RATIONALE: Although both work, * closer to the final outcome.

Good
* item 1
* item 2
* item 3
Bad   
- item 1
- item 2
- item 3

  • Use _ for italics (not *).

    RATIONALE: Although both work, _ is easier to relate to italics.

Good
He _really_ meant it.
Bad   
He *really* meant it.