Markdown笔记

Posted by wsxq2 on 2018-04-07
TAGS:  Markdown   note  

本文最后一次编辑时间：2020-06-18 17:52:58 +0800

本文是笔者学习Markdown的笔记，内容主要截取自下述学习曲线中的kramdown Quick Reference和GFM Guides，主要以示例的形式说明Markdown的语法，用作复习和参考。

由于笔者在GitHub Pages上写博客，故而终极目标为熟悉GFM。学习曲线(注意和实践相结合)为：

  1. Markdown 快速入门(中文)
  2. Markdown 完整说明(中文)
  3. kramdown Quick Reference(英文)
  4. kramdown Syntax(英文)
  5. GFM Guides(英文)
  6. 关于 Markdown 的一些奇技淫巧(中文)
  7. GFM spec(英文)

其中，Markdown即指最初版本的Markdown；kramdown是Markdown的众多拓展之一；GFM则是GitHub Flavored Markdown的缩写，也是Markdown的拓展。

目录：

Kramdown Quick Reference

kramdown是Markdown的众多扩展之一，是Ruby开发的解释器，吸取了Maruku和PHP Markdown Extra几乎所有的特点，且是Github Pages唯一支持的解释器。有关Markdown拓展的详细信息请前往Markdown的各种扩展

kramdown(sic, not Kramdown or KramDown, just kramdown) is a free MIT-licensed Ruby library for parsing and converting a superset of Markdown. It is completely written in Ruby, supports standard Markdown (with some minor modifications) and various extensions that have been made popular by the PHP Markdown Extra package and Maruku.
It is probably the fastest pure-Ruby Markdown converter available (September 2014), being about 3x faster than Maruku and about 4.5x faster than BlueFeather.

Block-level Elements

Paragraphs

separate: blank line



1
2
3



The first paragraph.

Another paragraph

Explicit line breaks: two spaces or two backslashes



1
2



This is a paragraph  
which contains a hard line break.

Headers

A header must always be preceded by a blank line except at the beginning of the document

Setext style:



1
2
3
4
5



First level header
==================

Second level header
-------------------

atx style:



1
2
3
4
5
6
7
8
9
10
11



# H1 header

## H2 header

### H3 header

#### H4 header

##### H5 header

###### H6 header

set the option auto_ids to false:



1
2
3



{::options auto_ids="false" /}

# A header without an ID

Blockquotes



1
2
3
4
5
6
7



> A sample blockquote.
>
> >Nested blockquotes are
> >also possible.
>
> ## Headers work too
> This is the outer quote again.

Code Blocks



1
2
3



This is a sample code block.

    Continued here.





1
2
3
4
5
6



~~~~~~
This is also a code block.
~~~
Ending lines must have at least as
many tildes as the starting line.
~~~~~~~~~~~~





1
2
3
4
5



~~~ ruby
def what?
  42
end
~~~

Horizontal Rules



1
2
3
4
5
6
7



* * *

---

  _  _  _  _

---------------

Lists

ordered:



1
2
3
4



1. This is a list item
2. And another item
2. And the third one
   with additional text





1
2
3
4
5
6
7



1.  This is a list item

    > with a blockquote

    # And a header

2.  Followed by another item





1
2
3
4
5



1. Item one
   1. sub item one
   2. sub item two
   3. sub item three
2. Item two





1
2
3
4



This is a paragraph.
1. This is NOT a list.

1. This is a list!

unordered:



1
2
3



* Item one
+ Item two
- Item three

Definition Lists



1
2
3
4
5
6
7



term
: definition
: another definition

another term
and another term
: and a definition for the term





1
2
3
4



term

: definition
: definition





1
2
3
4
5
6
7



This *is* a term

: This will be a para

  > a blockquote

  # A header

Tables



1
2



| A simple | table |
| with multiple | lines|





1
2
3
4
5
6
7
8
9
10



| Header1 | Header2 | Header3 |
|:--------|:-------:|--------:|
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|----
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|=====
| Foot1   | Foot2   | Foot3
{: rules="groups"}

HTML elements



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



<div style="float: right">
Something that stays right and is not wrapped in a para.
</div>

{::options parse_block_html="true" /}

<div>
This is wrapped in a para.
</div>
<p>
This can contain only *span* level elements.
</p>

Block Attributes



1
2



> A nice blockquote
{: title="Blockquote title"}





1
2
3



> A nice blockquote
{: .class1 .class2}






1
2



> A nice blockquote
{: #with-an-id}





1
2
3



{:refdef: .c1 #id .c2 title="title"}
paragraph
{: refdef}





1
2
3



{:refdef: .c1 #id .c2 title="title"}
paragraph
{: refdef .c3 title="t" #para}

Extensions



1
2
3
4
5
6
7
8
9



This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.

Extensions can also be used
inline {::nomarkdown}**see**{:/}!





1
2
3



{::options auto_ids="false" /}

# Header without id

Span-Level Elements(Text Modifiers)

Emphasis



1
2



This is *emphasized*,
_this_ too!





1
2



This is **strong**,
__this__ too!





1



This w**ork**s as expected!





1
2



A [link](http://kramdown.gettalong.org)
to the kramdown homepage.





1
2



A [link](http://kramdown.gettalong.org "hp")
to the homepage.





1
2
3
4



A [link][kramdown hp]
to the homepage.

[kramdown hp]: http://kramdown.gettalong.org "hp"





1
2
3



A link to the [kramdown hp].

[kramdown hp]: http://kramdown.gettalong.org "hp"





1



An image: ![alt text](img/image.jpg)

Inline Code



1
2
3



Use `Kramdown::Document.new(text).to_html`
to convert the `text` in kramdown
syntax to HTML.





1
2



Use backticks to markup code,
e.g. `` `code` ``.

Footnotes



1
2
3
4



This is a text with a
footnote[^1].

[^1]: And here is the definition.





1
2
3
4
5
6
7



This is a text with a
footnote[^2].

[^2]:
    And here is the definition.

    > With a quote!

Abbreviations



1
2
3
4



This is an HTML
example.

*[HTML]: Hyper Text Markup Language

HTML Elements



1
2



This is <span style="color: red">written in
red</span>.

Inline Attributes



1



This is *red*{: style="color: red"}.

GFM Guides

You can use Markdown most places around GitHub:

  • Gists
  • Comments in Issues and Pull Requests
  • Files with the .md or .markdown extension

For more information, see “Writing on GitHub” in the GitHub Help.

GitHub Flavored Markdown

GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com.

Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests. These include @mentions as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.

Syntax highlighting

可以使用```而不仅仅是kramdown中的~~~。

```javascript
function fancyAlert(arg) {
  if(arg) {
      $.facebox({div:'#foo'})
  }
}
```

Task Lists



1
2
3
4



- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item

SHA references



1
2
3



16c999e8c71134401a78d4d46435517b2271d6ac
mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac

Issue references within a repository



1
2
3



#1
mojombo#1
mojombo/github-flavored-markdown#1

Username @mentions



1



@wsxq2 get up! your program get a new bug.

Automatic linking for URLs



1



http://www.github.com/

Strikethrough



1



~~this~~

Emoji

Emoji Cheat Sheet



1



@octocat :+1: This PR looks great - it's ready to merge! :shipit:

技巧

参考链接：关于 Markdown 的一些奇技淫巧

Math Formulas(公式) support

MathJax is more complete than KaTeX and it is supported on GitHub Pages, see Jekyll Math Support section. So you choose to use MathJax, add this script in your page:



1



<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

Then:

you can use an inline formula $$\forall x \in R$$ like this one

or display a centered formula like this:

$$
M = \left( \begin{array}{ccc}
x_{11} & x_{12} & \ldots \\
x_{21} & x_{22} & \ldots \\
\vdots & \vdots & \ldots \\
\end{array} \right)
$$

详情：Math on GitHub Pages

关于id

引用id：[点这里](#id)

放置id：

  1. 标题id：### 我是标题 {#i-am-id}
  2. 文中任意位置id：<a name="id-lalala"></a>
  3. 依附于某个元素的id。由于 GitHub Pages 的 markdown 解释器是kramdown，所以支持kramdown的Block Attribute和Inline Attribute。如下所示： 
    

    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    		

    > A nice blockquote
{: #with-an-id}

{:refdef1: .c1 #id .c2 title="title"}

paragraph
{: refdef1}

{:refdef2: .c1 #id .c2 title="title"}

paragraph
{: refdef2 .c3 title="t" #para}

This is *red*{: style="color: red"}.

    参见 kramdown Quick Reference

任意位置换行

<br />

图文混排

使用<img>标签来贴图，然后指定align属性。如：



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



<img align = "right" src = "https://raw.githubusercontent.com/mzlogin/mzlogin.github.io/master/images/posts/markdown/demo.png" />
这是一个示例图片。

图片显示在 N 段文字的右边。

N 与图片高度有关。

刷屏行。

刷屏行。

到这里应该不会受影响了，本行应该延伸到了图片的正下方，所以我要足够长才能确保不同的屏幕下都看到效果。

控制图片大小和位置



1



<div align="center"><img width="65" height="75" src="https://raw.githubusercontent.com/mzlogin/mzlogin.github.io/master/images/posts/markdown/demo.png"/></div>

格式化表格

对于Vim编辑器，可以使用vim-table-mode插件

使用 Emoji

To enable emoji, you must add the following line to your site’s _config.yml file:

plugins:
  - jemoji

使用方法如下：



1



我和我的小伙伴们都笑了。:smile:

更多可用Emoji代码参见https://www.webpagefx.com/tools/emoji-cheat-sheet/。

行首缩进

直接在Markdown里用空格和Tab键缩进在渲染后会被忽略掉，需要借助HTML转义字符在行首添加空格来实现，&ensp;代表半角空格，&emsp;代表全角空格。如：



1



&emsp;&emsp;春天来了，又到了万物复苏的季节。

自动维护目录

对于Vim编辑器，可以使用插件vim-markdown-toc， :smile:

和 Word 互相转换



1
2



pandoc -f gfm -t docx 2019-07-07-科学上网.md -o 科学上网.docx
pandoc -f docx -t gfm 科学上网.docx 2019-07-07-科学上网.md

详情参见 pandoc