Markdown Syntax in Hexo

Posted on Edited on In Word count in article: 3.6k Reading time ≈ 13 mins.

Writing a blog requires using Markdown, so it’s necessary to be familiar with its syntax rules. Although Markdown syntax is relatively simple, looking up each rule one by one can be quite tedious (the table of contents messed up due to the preview of headings…).

Common Markdown syntax rules are:

This post was translated from my Chinese blog post with the aid of ChatGpt.

  • Headings (I moved the headings to the bottom of the webpage, which messed up the table of contents…)
  • Bold and Italic Formatting
  • Blockquotes
  • Horizontal Rules
  • Images
  • Hyperlinks
  • Lists
  • Tables
  • Code Blocks
  • Small Text
  • Escaping Special Characters
  • Font Color and Size
  • Text Alignment
  • Checkboxes
  • First-line Indentation
  • Linking to Other Articles
  • Text Background Color
  • Tags
  • Tabs
  • Buttons

Bold and Italic Formatting

To italicize text, you need to add one * on each side of the text.
To make text bold, you need to add two * on each side of the text.
To make text both bold and italic, you need to add three * on each side of the text.
To add strikethrough to text, you need to add two ~~ on each side of the text.
Markdown doesn’t support underlining directly, you can use the HTML <u> tag to achieve it.

Example

1
2
3
4
5
*Italicized text*
**Bold text**
***Bold and italicized text***
~~Strikethrough text~~
<u>Underlined text</u>

Preview

Italicized text
Bold text
Bold and italicized text
Strikethrough text
Underlined text

Blockquotes

To create a blockquote, you need to add a > before the quoted text. Blockquotes can be nested, for example using two >> or three >>>.

Example

1
2
3
> Quoted text
>> Nested quoted text
>>> Further nested text

Preview

Quoted text

Nested quoted text

Further nested text

Horizontal Rule

Horizontal rules are created by using three or more consecutive * or - characters. Leave a blank line before and after when there are paragraphs.

Example

1
2
3
4
5
6
7
***

*****

---

-----

Preview

Hyperlinks

Syntax

1
[Link Text](URL)

Example

1
[GitHub](https://github.com)

Preview

GitHub

Deprecated Old Syntax

Syntax

1
[Link Text](URL Link Title)

Link Title is optional and will be displayed when hovering over the link.

Example

1
[GitHub](https://github.com GitHub)

Preview

[GitHub](https://github.com GitHub)

Example

1
2
3
Using 1 as a variable [GitHub][1]
	Assign 1 at the end
[1]:https://github.com GitHub

Preview

Using 1 as a variable [GitHub][1]
Assign 1 at the end
[1]:https://github.com

Lists

There are ordered lists and unordered lists. Both can be nested by adding a Tab or three spaces before the next list item.
For ordered lists, you can use the symbols *, +, or -.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
- C
+ C++
* Java

- Nested 1
	- Nested 2
		- Nested 3

1. C
2. C++
3. Java

1. Nested 1
	1. Nested 2
	2. Nested 2 (1)
	3. Nested 2 (2)
		1. Nested 3
		2. Nested 3 (1)
	2. Nested 2 (3)
2. Nested 1 (1)

Preview

  • C
  • C++
  • Java
  • Nested 1
    • Nested 2
      • Nested 3

  1. C

  2. C++

  3. Java

  4. Nested 1

    1. Nested 2
    2. Nested 2 (1)
    3. Nested 2 (2)
      1. Nested 3
      2. Nested 3 (1)
    4. Nested 2 (3)

  5. Nested 1 (1)

Tables

Example

1
2
3
4
Header 1 | Header 2 | Header 3
-|:-:|-:
Content 1 | Content 2 | Content 3
Content 4 | Content 5 | Content 6

In the second row, alignment is specified:

  • Default is left-aligned, represented by -
  • Center-aligned is :-:
  • Right-aligned is -:

Preview

Header 1Header 2Header 3
Content 1Content 2Content 3
Content 4Content 5Content 6

Code

Code is enclosed with backticks ` (located on the keyboard left of the 1 key, not the right side quotes). Triple backticks can create code blocks. If you want to nest code blocks, the outer code block should have three more backticks than the inner one, and so on. The characters following the triple backticks indicate the language type. The example below includes additional brackets for demonstration purposes.

Basic Syntax

Example

1
2
3
4
5
6
7
[```cpp]
#include <stdio.h>
int main(void){
    printf("Hello World!");
    return 0;
}
[```]

Preview

1
2
3
4
5
#include <stdio.h>
int main(void){
    printf("Hello World!");
    return 0;
}

Advanced Syntax

Note that the link and link text must exist simultaneously, and the link format should be correct. Otherwise, they will be treated as headers.
Example

1
2
3
4
5
6
7
```[language] [title] [link] [link text]
#include <stdio.h>
int main(void){
	printf("Hello World!");
    return 0;
}
```

Preview

My TitleLink Text
1
2
3
4
5
#include <stdio.h>
int main(void){
	printf("Hello World!");
    return 0;
}

Code Block Language Specification

Hexo uses highlight.js for code highlighting by default. Below are commonly used language styles. For more styles, please visit the official website. The text following the triple backticks indicates the language format.

LanguageFormat
Bashbash, sh, zsh
C#csharp, cs
Cc,h
C++cpp, hpp, cc, hh, c++, h++, cxx, hxx
CSScss
Djangodjango, jinja
DOSdos, bat, cmd
Excelexcel, xls, xlsx
Gogo, golang
HTMLxml, html, xhtml, rss, atom, xjb, xsd, xsl, plist, svg
iniini
JSONjson
Javajava, jsp
JavaScriptjavascript, js, jsx
LaTeXtex
Matlabmatlab
Markdownmarkdown, md, mkdown, mkd
Makefilemakefile, mk, mak, make
Nginxnginx, nginxconf
Objective-Cobjectivec, mm, objc, obj-c, obj-c++, objective-c++
PHPphp
PostgreSQL & PL/pgSQLpgsql, postgres, postgresql
PowerShellpowershell, ps, ps1
Processingprocessing
Pythonpython, py, gyp
Rr
Rubyruby, rb, gemspec, podspec, thor, irb
SQLsql
Shellshell, console
Stylusstylus, styl
Swiftswift
TypeScripttypescript, ts
VBScriptvbscript, vbs, vb
VB.Netvbnet
Vim Scriptvim
x86 Assemblyx86asm
YAMLyml, yaml

Small Text

To create small text, add <small> at the beginning and </small> at the end of the text.

Example
<small>Small Text</small>

Preview

Small Text

Escaping Characters

When using special symbols (such as #), you need to add a backslash \ before the symbol to escape it. Otherwise, the symbol won’t display properly.

Example

1
2
3
4
5
\#
\*
\!
\+
\-

Preview

#
*
!
+
-

Special Character Escapes

Some special characters require using escape sequences. Below is a reference table. Not all situations require escapes, this is for reference only.

Special CharacterEscapeChinese NameEnglish Name
“!”&#33;感叹号Exclamation mark
"&#34; &quot;双引号Quotation mark
#&#35;数字标志Number sign
$&#36;美元标志Dollar sign
%&#37;百分号Percent sign
&&#38; &amp;与Ampersand
'&#39;单引号Apostrophe
(&#40;小括号左边部分Left parenthesis
)&#41;小括号右边部分Right parenthesis
*&#42;星号Asterisk
+&#43;加号Plus sign
<&#60; &lt;小于号Less than
=&#61;等于符号Equals sign
-&#45; &minus;减号Minus
>&#62; &gt;大于号Greater than
?&#63;问号Question mark
@&#64;艾特Commercial at
[&#91;中括号左边部分Left square bracket
\&#92;反斜杠Reverse solidus (backslash)
]&#93;— 中括号右边部分Right square bracket
{&#123;大括号左边部分Left curly brace
|&#124;竖线Vertical bar
}&#125;大括号右边部分Right curly brace
 &emsp;空格Space

Font Color and Size

  • Hexo only supports black font color, but you can use HTML to adjust the color. Use <font color="ff0000"> and </font> to wrap the text you want to change color for. Replace ff0000 with other color codes.
  • Font size can also be adjusted using HTML. Use <font size=12> and </font> to wrap the text you want to resize. font size= is followed by the desired font size.
  • Font style can also be adjusted using HTML. Use <font face="FontName"> and </font> to wrap the text you want to change the font for. font face= is followed by the desired font name.
  • Color, font size, and font style can be combined.

Example

1
2
3
4
<font color="ff0000">Red Text</font>
<font size=2>Size 2 Text</font>
<font face="华文彩云">Huawen Caiyun Font</font>
<font face="华文彩云" size=2 color="ff0000">Size 2 Red Huawen Caiyun Font</font>

Preview
Red Text
Size 2 Text
Huawen Caiyun Font
Size 2 Red Huawen Caiyun Font

Centering Text

Centering text can also be achieved using HTML tags.

Example

1
<center>This is centered text</center>
This is centered text

Deprecated Methods

Example

1
2
3
{% centerquote %}This is centered text{% endcenterquote %}
 <blockquote class="blockquote-center">This is centered text</blockquote>
{% cq %}This is centered text{% endcq %}

Preview

This is centered text

This is centered text

This is centered text

Checkbox

A checkbox-like feature, similar to a todo list. Note that these checkboxes are for display purposes only and cannot be interacted with.

Example

1
2
- [ ] This is an unchecked checkbox
- [x] This is a checked checkbox

Preview

  • This is an unchecked checkbox
  • This is a checked checkbox

Deprecated Indentation

Indentation (Deprecated)

Hexo ignores indented spaces, so you need to use escapes for first-line indentation.

Example

1
&emsp;&emsp;This text is indented

Preview
  This text is indented

Linking to Other Articles

Hexo supports linking to other articles using the syntax {% post_path slug %} and {% post_link slug [title] %}, where slug is the filename of the Markdown file you want to link to, and title is the title of the linked article.

1
{% post_link hexo-guide [Hexo Blog Guide to Avoiding Pitfalls] %}

Preview

[Hexo Blog Guide to Avoiding Pitfalls]

Text Background Color

Setting the background color for text requires using HTML tables. Use the bgcolor attribute followed by the color’s English name.

Example

1
<table><tr><td bgcolor=lightblue>亮蓝色背景色</td></tr></table>

Preview

亮蓝色背景色

Note Tag

Configuration

You need to choose a style for the Note tag in the Next theme configuration. Open the _config.next.yml file and search for Note tag (bs-callout). Below is my configuration. There are four available style options, and you can preview them here. The icon option is used to determine whether to display an icon. The titles within the Note tag will also appear in the table of contents.

1
2
3
4
5
6
7
8
9
10
11
12
# Note tag (bootstrap callout)
note:
  # Note tag style values:
  #  - simple    bootstrap callout old alert style. Default.
  #  - modern    bootstrap callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: flat
  icons: true
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

Usage

1
2
3
{% note [class] [no-icon] [summary] %}
Any content (support inline tags too).
{% endnote %}
  • [class]: An optional parameter that controls the style of the Note. There are six options:
    • default
    • primary
    • success
    • info
    • warning
    • danger.
  • [no-icon]: An optional parameter. When enabled, the Note’s icon will not be displayed.
  • [summary]: An optional parameter. Serves as a summary or overview of the Note’s content. When enabled, the remaining content will be collapsed.

Examples

1
2
3
4
{% note %}
### Default Style with Nothing
I'm a default style with nothing.
{% endnote %}

Default Style with Nothing

I’m a default style with nothing.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{% note default %}
### Default Style
I'm a default style.
{% endnote %}

{% note primary %}
### Primary Style
I'm a primary style.
{% endnote %}

{% note info %}
### Info Style
I'm an info style.
{% endnote %}

{% note success %}
### Success Style
I'm a success style.
{% endnote %}

{% note warning %}
### Warning Style
I'm a warning style.
{% endnote %}

{% note danger %}
### Danger Style
I'm a danger style.
{% endnote %}

Default Style

I’m a default style.

Primary Style

I’m a primary style.

Info Style

I’m an info style.

Success Style

I’m a success style.

Warning Style

I’m a warning style.

Danger Style

I’m a danger style.


1
2
3
4
{% note info no-icon %}
### Info Style without Icon
I'm an info style without an icon.
{% endnote %}

Info Style without Icon

I’m an info style without an icon.


1
2
3
4
{% note info Style with Summary %}
### Style with Summary
I'm a style with a summary.
{% endnote %}

Style with Summary

Style with Summary

I’m a style with a summary.


Old Method (Not Recommended)

Wrap the content to be displayed with <div>. Use the class attribute to specify the note’s style. Adding no-icon will hide the icon.
Example

1
2
3
4
5
6
7
<div class="note default"><p>default</p></div>
<div class="note primary"><p>primary</p></div>
<div class="note success"><p>success</p></div>
<div class="note info"><p>info</p></div>
<div class="note warning"><p>warning</p></div>
<div class="note danger"><p>danger</p></div>
<div class="note default no-icon"><p>danger no-icon</p></div>

Preview

default

primary

success

info

warning

danger

danger no-icon

Label标签

Adjust the label’s style before the @, and input the content to be displayed after the @.
Example

1
2
3
4
5
6
{% label default@This is default %}
{% label primary@This is primary %}
{% label success@This is success %}
{% label info@This is info %}
{% label warning@This is warning %}
{% label danger@This is danger %}

Preview

This is default This is primary This is success This is info This is warning This is danger

Tab tag - Options Tab

Configuration

Search for Tabs tag in the Next theme files, and set enable to true. Below is my configuration:

1
2
3
4
5
6
7
# Tabs tag
tabs:
  enable: true
  transition:
    tabs: true
    labels: true
  border_radius: 0

Usage

There are many customization options available.
Example

1
2
3
4
5
6
7
8
9
10
11
{% tabs First unique name %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->
<!-- tab -->
**This is Tab 2.**
<!-- endtab -->
<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Preview

This is Tab 1.

This is Tab 2.

This is Tab 3.

Example
The number 3 in the first line indicates the default tab to display. Setting it to -1 means no default tab will be displayed.

1
2
3
4
5
6
7
8
9
10
11
{% tabs Second unique name, 3 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->
<!-- tab -->
**This is Tab 2.**
<!-- endtab -->
<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Preview

This is Tab 1.

This is Tab 2.

This is Tab 3.

Example
The names and icons of the options can be customized. Adjust them in <!-- tab Custom Name@Custom Icon -->.

1
2
3
4
5
6
7
8
9
10
11
{% tabs Third unique name %}
<!-- tab Solution 1@text-width -->
**This is Tab 1.**
<!-- endtab -->
<!-- tab Solution 2@code -->
**This is Tab 2.**
<!-- endtab -->
<!-- tab Solution 3@bold -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Preview

This is Tab 1.

This is Tab 2.

This is Tab 3.

Buttons

Example
Use button or btn, followed by the link you want to navigate to. If no link is provided, it defaults to the current page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Display text only, where Text is the content of the button
{% button https://siriusq.top/, Home %}

// Multiple buttons side by side
{% btn https://siriusq.top/, Home %} {% btn #, Text & Title,, Title %}

// Display icon only
<p>{% btn #,, home fa-5x %}
{% btn #,, home fa-4x %}
{% btn #,, home fa-3x %}{% btn #,, home fa-2x %}{% btn #,, home fa-lg %}{% btn #,, home %}</p>

// Display text and icon
<p>{% btn #, Text & Icon (buggy), home %}
{% btn #, Text & Icon (fixed width), home fa-fw %}</p>

Preview
Display text only:

Home

Multiple buttons side by side:

Home Text & Title

Display icon only:

Display text and icon:

Text & Icon (buggy) Text & Icon (fixed width)

Link Grid

Can be used individually or combined to create a grid of links.

Example

1
2
3
{% linkgrid %}
Siriusq | https://siriusq.top/ | May the Force be with you. | /images/apple-touch-icon-next.png
{% endlinkgrid %}

Siriusq

May the Force be with you.


1
2
3
4
5
6
{% linkgrid %}
Siriusq | https://siriusq.top/ | May the Force be with you. | /images/apple-touch-icon-next.png
Siriusq | https://siriusq.top/ | May the Force be with you. | /images/apple-touch-icon-next.png
Siriusq | https://siriusq.top/ | May the Force be with you. | /images/apple-touch-icon-next.png
Siriusq | https://siriusq.top/ | May the Force be with you. | /images/apple-touch-icon-next.png
{% endlinkgrid %}

Siriusq

May the Force be with you.

Siriusq

May the Force be with you.

Siriusq

May the Force be with you.

Siriusq

May the Force be with you.

Inserting Music/Videos

Due to the limited space provided by GitHub Pages, it’s recommended to upload music and videos to platforms like Bilibili (B站) or YouTube and then embed them using HTML language. Simply copy the sharing link provided by the platform. You can use the width attribute to set the width and the height attribute to set the height.

<video>tag

Use source src to set video link
Example

1
2
3
<video width="480" height="320" controls>
<source src="movie.mp4">
</video>

Preview(Without a real video)

<embed>tag

Example

1
<embed src='http://player.youku.com/player.php/sid/XMzUzNjg1OTQzNg==/v.swf' allowFullScreen='true' quality='high' width='480' height='400' align='middle' allowScriptAccess='always' type='application/x-shockwave-flash'></embed>

Preview

<iframe>标签

Example

1
<iframe height=400 width=600 src="//player.bilibili.com/player.html?aid=14176961&cid=23141262&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

Preview(My own video)
The following links are obtained through the web-based sharing - embed code feature. Simply copy and paste them.

Insert Images

The steps are as follows:

  • Install the Image Plugin
    • Open Git bash in the root directory of your blog.
    • Enter the command npm install hexo-asset-image and wait for the installation to complete.
  • Modify the Configuration File
    • Open the _config.yml file in the root directory of your blog.
    • Search for post_asset_folder and set it to true.
  • How to Use
    • When you create a new blog post using the command hexo new "title", a folder with the same name will be generated.
    • Place the images you want to insert into the same-named folder.
    • Use the markdown format to insert images. Any of the following three methods can be used. The last method allows you to control the size using the numbers at the end.
      1
      2
      3
      ![Alternative Text](Blog Title/Image Name.JPG)
      ![Alternative Text](/Blog Title/Image Name.JPG)
      {% img full-image /Blog Title/Image Name.JPG 180 180 Image Name %}
    • Run hexo s to preview the effect locally.

Format

Example

1
2
3
![Alternative Text](Markdown Writing Syntax/201904133.JPG)
![Alternative Text](/Markdown Writing Syntax/201904133.JPG)
{% img full-image /Markdown Writing Syntax/201904133.JPG 180 180 Image Name %}

Preview

Alternative Text
Alternative Text

Deprecated Legacy Approach

Deprecated Legacy Approach for Next 8

Insert images using a link-based format:

1
![Image Alt](Image URL Image Title)

Here, Image Alt is the text below the image, similar to a caption; Image URL is the image’s address; Image Title is what will be displayed when the mouse hovers over the image (this is optional).

A Small Detail

The Next theme generates a gray border around images by default, affecting aesthetics. To address this, you need to modify the post-expand.styl file in blog_directory\themes\next\source\css\_common\components\post.
Search for img in the file and modify it to:

1
2
3
4
5
6
img {
    box-sizing: border-box;
    margin: 0 auto 25px;
    padding: 3px;
    border: none;
  }

After redeploying, the gray border will disappear.

Note

Make sure the image file extension’s case matches.

Headings

To create headings, simply add # followed by a space before your text. This supports six levels of headings and different-sized titles. Make sure you don’t forget the space after #, as omitting it will cause the text to display as regular content.

Example

1
2
3
4
5
6
7
8
9
10
11
12
# Level 1 Heading
## Level 2 Heading
### Level 3 Heading
#### Level 4 Heading
##### Level 5 Heading
###### Level 6 Heading

Major Heading
===

Minor Heading
---

Preview

Level 1 Heading

Level 2 Heading

Level 3 Heading

Level 4 Heading

Level 5 Heading
Level 6 Heading

Major Heading

Minor Heading

Completion

These are some of the commonly used Markdown syntax in Hexo. Mission accomplished!