SE-EDU
  • Home
  • About
  • 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 with throw off grammar checkers and make it harder to modify content later (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.