Skip to content

Latest commit

 

History

History
139 lines (91 loc) · 3.19 KB

README.md

File metadata and controls

139 lines (91 loc) · 3.19 KB

Markdown

Stricter Markdown generates consistent output. Stricter Markdown also makes it easier for your teammates to contribute. I recommend following the CommonMark specification as it was designed to be unambiguous.

Use a linter

The easiest way to learn Markdown is to rely on a linter. I recommend the Visual Studio Code extension markdownlint. The extension will highlight violations and provide a link explaining why the rule was violated and how to fix it. The rules are available here.

The most commonly violated rules are:

  • Surround headings, lists and code fences by blank lines
  • Single top-level heading

Link to anchor

You can link to a heading within the same page

[Link to title text](#a-title)

#### A title

The title needs to be URL encoded, space can be replaced by dash.

Fenced code block language

Setting a language on a fenced code block will allow syntax highlighting.

The following JavaScript snippet:

```js
console.log("Hello World!");
```

Will render as:

console.log("Hello World!");

You can use plaintext to prevent highlighting:

```plaintext
I'm just a text
```

Will render as:

I'm just a text

Code span

Code span allows you to use a code fence within a sentence:

I love `PHP`.

Will render as:

I love PHP.

Tables

GitHub Flavored Markdown supports tables as an extension.

| Column 1 title         | Column 2 title         |
| ---------------------- | ---------------------- |
| Column 1 row 1 content | Column 2 row 1 content |
| Column 1 row 2 content | Column 2 row 2 content |

Will be rendered as:

Column 1 title Column 2 title
Column 1 row 1 content Column 2 row 1 content
Column 1 row 2 content Column 2 row 2 content

Colons can be used to align a column. The number of spaces or dashes is not important as long as there are at least three dashes or colons.

| Left Align | Center Align | Right Align |
| :--------- | :----------: | ----------: |
| 1          | 2            | 3           |

Will be rendered as:

Left Align Center Align Right Align
1 2 3

Use headings instead of emphasis

Sometimes headings don't render quite at the right size and developers resort to use bold instead. They then lose the ability to link to a section and the semantic meaning of a heading.

Prefer:

### Title

To:

**Title**

Bonus

Define reusable links

You can declutter your Markdown by defining the links at the bottom of the page

Usage:

[Text of the link][link-identifier]

Definition:

[link-identifier]: https://commonmark.org/help/