Markdown 语法
让我们面对现实吧：为网络编写内容令人厌烦。WYSIWYG编辑器有助于缓解这项任务，但它们通常会导致可怕的代码，或者更糟糕的是，丑陋的网页。
Markdown是编写HTML的更好方法，没有通常随之而来的所有复杂性和丑陋。
一些关键的好处是：
- Markdown学习简单，额外的字符很少，因此编写内容也更快。
- 在Markdown中书写时出错的可能性更小。
- 生成有效的HTML输出。
- 将内容和视觉显示分开，这样您就不会弄乱网站的外观。
- 写任何你喜欢的文本编辑器或Markdown应用程序。
- Markdown使用起来很愉快！
《Markdown》的作者John Gruber是这样说的：
Markdown格式语法的首要设计目标是使其尽可能具有可读性。其想法是，Markdown格式的文档应该是可按原样发布的，作为纯文本，而不会看起来像是用标记或格式说明标记的。虽然Markdown的语法受到了现有的几种文本到HTML过滤器的影响，但Markdown语法的最大灵感来源是纯文本电子邮件的格式. 约翰·格鲁伯
不再拖延，让我们来看看Markdown的主要元素以及由此产生的HTML是什么样子的:
Bookmark this page and the official Commonmark reference for easy future reference!
段落
在Markdown中，您的内容通常跨越整个可用文档宽度。这被称为块。在生成的文档中，块总是用空格与相邻的块隔开。 任何不以特殊符号开头的文本都被写成普通的纯文本段落块，并且必须用空行与相邻的块隔开。
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
标题
一个好主意是使用标题和副标题来组织您的内容。
Html–从h1到h6的标题，每一级都有一个#。
在Hugo中，您通常不使用h1，因为这是由您的主题生成的，并且在一个文档中应该只有一个这样的元素。
# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Headingh1 Heading
h2 Heading
h3 Heading
h4 Heading
h5 Heading
h6 Heading
Horizontal Rules
To further structure your content you can add horizontal rules. They create a “thematic break” between paragraph blocks. In Markdown, you can create it with three consecutive dashes ---.
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
---
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Text Markers
Bold
You can show importance of a snippet of text with a heavier font-weight by enclosing it with two asterisks **.
I am rendered with **bold text**I am rendered with bold text
Italics
You can emphasize a snippet of text with italics by enclosing it with underscores _.
I am rendered with _italicized text_I am rendered with italicized text
Strikethrough
In GFM (GitHub Flavored Markdown) you can do strikethroughs by enclosing text with two tildes ~~.
~~Strike through this text~~Strike through this text
Text substitution
This Markdown dialect supports an extension to combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code.
Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.
Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.
Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.
Three consecutive dots `...` are replaced by an ellipsis **...** entity.Double quotes " and single quotes ' of enclosed text are replaced by “double curly quotes” and ‘single curly quotes’.
Double dashes -- and triple dashes --- are replaced by en-dash – and em-dash — entities.
Double arrows pointing left << or right >> are replaced by arrow « and » entities.
Three consecutive dots ... are replaced by an ellipsis … entity.
Lists
Unordered
You can write a list of items in which the order of the items does not explicitly matter.
It is possible to nest lists by indenting an item for the next sublevel.
You may use any of -, * or + to denote bullets for each list item but should not switch between those symbols inside one whole list.
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Faucibus porta lacus fringilla vel- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Faucibus porta lacus fringilla vel
Ordered
You can create a list of items in which the order of items does explicitly matter.
It is possible to nest lists by indenting an item for the next sublevel.
Markdown will automatically number each of your items consecutively. This means, the order number you are providing is irrelevant.
1. Lorem ipsum dolor sit amet
3. Consectetur adipiscing elit
1. Integer molestie lorem at massa
7. Facilisis in pretium nisl aliquet
99. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
17. Eget porttitor lorem- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Tasks
In GFM (GitHub Flavored Markdown) you can add task lists resulting in checked or unchecked non-clickable items
- [x] Basic Test
- [ ] More Tests
- [x] View
- [x] Hear
- [ ] Smell- Basic Test
- More Tests
- View
- Hear
- Smell
Definitions
This Markdown dialect supports an extension to add definition lists. Definition lists are made of terms and definitions of these terms, much like in a dictionary.
A definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term. You can also associate more than one term to a definition.
If you add empty lines around the definition terms, additional vertical space will be generated. Also multiple paragraphs are possible
Apple
: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
: An American computer company.
Orange
: The fruit of an evergreen tree of the genus Citrus.
You can make juice out of it.
: A telecommunication company.
You can't make juice out of it.- Apple
- Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
- An American computer company.
- Orange
- The fruit of an evergreen tree of the genus Citrus.
You can make juice out of it.
- A telecommunication company.
You can’t make juice out of it.
Code
Inline Code
Inline snippets of code can be wrapped with backticks `.
In this example, `<div></div>` is marked as code.In this example, <div></div> is marked as code.
Indented Code Block
A simple code block can be generated by indenting several lines of code by at least two spaces.
Be impressed by my advanced code:
// Some comments
line 1 of code
line 2 of code
line 3 of codeBe impressed by my advanced code:
// Some comments
line 1 of code
line 2 of code
line 3 of code
Fenced Code Block
If you want to gain more control of your code block you can enclose your code by at least three backticks ``` a so called fence.
In GFM (GitHub Flavored Markdown) you can also add a language specifier directly after the opening fence, ```js, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML.
See for additional documentation.
```js
grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};
```grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};Tables
In GFM (GitHub Flavored Markdown) you can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.
| Option | Description |
|--------|-------------|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. || Option | Description |
|---|---|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
Aligned Columns
Adding a colon on the left and/or right side of the dashes below any heading will align the text for that column accordingly.
| Option | Number | Description |
|-------:|:------:|:------------|
| data | 1 | path to data files to supply the data that will be passed into templates. |
| engine | 2 | engine to be used for processing templates. Handlebars is the default. |
| ext | 3 | extension to be used for dest files. || Option | Number | Description |
|---|---|---|
| data | 1 | path to data files to supply the data that will be passed into templates. |
| engine | 2 | engine to be used for processing templates. Handlebars is the default. |
| ext | 3 | extension to be used for dest files. |
Blockquotes
For quoting blocks of content from another source within your document add > before any text you want to quote.
Blockquotes can also be nested.
> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
Links
Autolink
In GFM (GitHub Flavored Markdown) absolute URLs will automatically be converted into a link.
This is a link to https://example.com.This is a link to https://example.com.
Basic Link
You can explicitly define links in case you want to use non-absolute URLs or want to give different text.
[Assemble](http://assemble.io)Link with Tooltip
For even further information, you can add an additional text, displayed in a tooltip on hovering over the link.
[Upstage](https://github.com/upstage/ "Visit Upstage!")Link References
Links can be simplyfied for recurring reuse by using a reference ID to later define the URL location. This simplyfies writing if you want to use a link more than once in a document.
[Example][somelinkID]
[somelinkID]: https://example.com "Go to example domain"Footnotes
Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes.
Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.
Footnotes can contain block elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items, just indent the following paragraphs by four spaces in the footnote definition.
That's some text with a footnote[^1]
[^1]: And that's the footnote.
That's some more text with a footnote.[^someid]
[^someid]:
Anything of interest goes here.
Blue light glows blue.Images
Basic Images
Images have a similar syntax to links but include a preceding exclamation mark.
Image with Tooltip
Like links, images can also be given a tooltip.
Image References
Images can also be linked by reference ID to later define the URL location. This simplyfies writing if you want to use an image more than once in a document.
![La Forge][laforge]
[laforge]: https://octodex.github.com/images/trekkie.jpg "Geordi La Forge"
Image Effects
This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. The default thru your hugo.toml or frontmatter parameter.
Resizing
Add query parameter width and/or height to the link image to resize the image. Values are CSS values (default is auto).
CSS Classes
Add a query parameter classes to the link image to add CSS classes. Add some of the predefined values or even define your own in your CSS.
Shadow
Border
Left
Right
Inline
Combination
Lightbox
Add the query parameter lightbox=false to the image link to disable the lightbox.
If you want to wrap an image in a link and lightbox=true is your default setting, you have to explicitly disable the lightbox to avoid it to hijacking your link like:
[](https://octodex.github.com/#homercat)
