Markdown Syntax

Posted on In

Preface

Hmm, another article talking about Markdown?

Well, I am not going through the Markdown syntax one by one in this article, I am pretty sure they are quite easy to master after some practices. But instead, I will talk about some hidden parts (at least to me😅) of the Markdown syntax, especially after using markdownlint extension.

If you are looking for a quick Markdown Cheat Sheet, you could refer to Markdown Guide. In summary, all basic syntax are supported for hexo with next theme (I am not sure whether theme matters, but let’s be precise); for the extended syntax, Table, Fenced Code Block, Definition List, Strikethrough and Task List (not sure the purpose of this in a blog article though) are supported. That’s good enough for writting a good blog article with Markdown, hooray🎉.

Horizontal Line

The default Horizontal Line from VS Code quick suggestion is ----------, which conflicts with markdownlint extension rule MD035 - Horizontal rule style. Hence it is either to ignore the rule (and break it) or to add another snippet to obey the rule.

1
2
3
4
5
6
"hr line": {
    // to obey markdownlint's MD035 - Horizontal rule style
    "description": "Insert consistent hr",
    "prefix": "hr",
    "body": "---"
},

Fenced Code Block

Code Block Language

With markdownlint extension rule MD040 - Fenced code blocks should have a language specified, we are required to specify the language for a Fenced Code Block.

1
2
3
4
```JavaScript
let var = 1;
const func = () => "func";
```

Then the issue is, what are the language that we can specify? The complete list is here.

I know it is a huge list! But the rule seems to be quite lenient for detecting the name of the language. For example, JavaScript could be written as js, JS, JavaScript or javascript and Python could be written as py, python or Python. It won’t affect the rendered HTML by GitHub or Hexo and VS Code is also able to highlight the syntax.

Bash Script

Often, I don’t know what to put for this type. After some research in the huge list mentioned earlier, my doubt is finally solved. It can be shell, bash, sh or zsh.

diff

When I discovered this diff type as one of the language option for Fenced Code Block, I realised this is extremely helpful to highlight what has been changed for not only code but also configuration, especially the latter.

1
2
3
some_config = "1"
- some_other_config = "2"
+ some_other_config = "3"

File Path in Hexo

In Hexo, we could add a space followed by the file path after adding language for Fenced Code Block (Note: this does not work on GitHub).

1
2
3
4
5
```diff configuration.file
some_config = "1"
- some_other_config = "2"
+ some_other_config = "3"
```

Fenced Code Block above will be rendered as:

configuration.file
1
2
3
some_config = "1"
- some_other_config = "2"
+ some_other_config = "3"

Referrence

GitHub known languages

Markdown Guide

Rules for markdownlint extension