Coding standards for Markdown

Adapted from SE-EDU’s markdown coding standard.

Coding Standards for Markdown!

Thought that it would be relevant since this blog is written in markdown!

Content here is relevant to CS2103T software engineering, under Admin > Standards/Conventions > Markdown.

Here, markdown refers the Github Flavored Markdown.

• Follow the syntax specified here.

• Do not wrap lines at a specific length, as Markdown is used to write natural language content which shoulde not be chopped into sentence framgents. Doing so could throw off grammer checkers and make it hard to modify content later.

• Add a blank line at the beginning of a list.
• Add a blank line at the beginning of a code block.
• Add a space at the start of a heading.
• Use blank lines to separate headings
• Use blockquote symbol in every line of the blockquote.
• 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.
  • If you use generic numbers, you can insert items into the middle of the list without modifying any existing items.
• Use * for bullet-points (not -), as * is closer to the final outcome.
• Use _ for italics (not *), as _ is easier to relate to italics.
• Use > for >, and &lt for <.

Useful styling text:

**This is bold text**
_This text is italicized_
~~This was mistaken text~~ (strikethrough)
**This text is _extremely_ important** (bold and nested italic)
***All this text is important*** (all bold and italic)
This is a <sub>subscript</sub> text
This is a <sup>superscript</sup> text

• You can quote text with a >
• To format code or text in its own distinct block, use triple backticks. ```
• To create an inline link, wrap link text in brackets [] and URL in parentheses ().
• Images: You can display an image by adding ! and wrapping the alt text in [].
• Lists: You can make an unordered list by preceding one or more lines of text with -, *, or +. To order your list, precede each line with a number.
• Nested Lists. Indent items in the list.

Unordered List:
- George Washington
* John Adams
+ Thomas Jefferson

Ordered List:
1. James Madison
1. James Monroe
1. John Quincy Adams

• Commenting in markdown: You can tell GitHub to hide content from the rendered Markdown by placing the content in an HTML comment.

[empty line]
[comment]: # (This actually is the most platform independent comment, by doing a pseudo empty link)

<!-- This content will not appear in the rendered Markdown -->

• Task Lists: preface list items with a hyphen and space followed by [ ]. To mark a task as complete, use [x].

- [x] task a
- [ ] some link to a github repo issue
- [ ] Add delight to the experience when all tasks are complete :tada:

• completed task
• task to be completed

Others:

• Using emojis: add emoji to your writing by typing :EMOJICODE:, a colon followed by the name of the emoji. (Github)
• Paragraphs: You can create a new paragraph by leaving a blank line between lines of text.
• Add footnotes to your content by using this bracket syntax: [^1]
• Alerts: you can add alerts in Github:

> An example showing the `tip` type prompt.
{: .prompt-tip }

> An example showing the `info` type prompt.
{: .prompt-info }

> An example showing the `warning` type prompt.
{: .prompt-warning }

> An example showing the `danger` type prompt.
{: .prompt-danger }

Alerts:

An example showing the tip type prompt.

An example showing the info type prompt.

An example showing the warning type prompt.

An example showing the danger type prompt.

See the source code for the text and typography here.

• Ignore markdown formatting by using escape: You can tell GitHub to ignore (or escape) Markdown formatting by using \ before the Markdown character.