CSDN-markdown扩展语法说明

李嘉胜
2023-12-01

目录


正文

概述

大部分情况下,Markdown的基本语法已够我们使用,比如随性记录点东西、非专业的分析文章等,一般只用到标题、区块引用、强调、列表这样的基本元素。但若要写专业性比较强的分析文章或技术性文章,这些基本语法就不够用了,因为我们经常会用到表格、脚注、想要自动生成文章目录等,若是涉及代码的技术文章,我们还希望代码支持高亮以提升阅读体验。这就需要用到Markdown的扩展语法了。

CSDN-markdown编辑器支持基于PageDown( Stack Overflow所使用的编辑器)的扩展,从而支持GFM(GitHub Flavored Markdown)的Markdown Extra语法。下面详细介绍这些可使用的扩展语法。


换行

在标准Markdown语法中,要想换行必须在一行的最后加两个空格才行,否则即使你在一行的末尾插入硬回车,这些文本仍然会被合并为一行,这个特性会导致大量非预期的格式化错误。

但是GFM则没有此要求。GFM会把段落内容中的换行视为真正的换行,而这很可能正是你所期望的。

下面这个段落被一个换行符分隔成了两行:

Roses are red
Violets are blue

将被渲染为:

Roses are red
Violets are blue


删除线

GFM也支持删除线的使用,只要用~~将需要删除的文本包围起来即可。

例子:

~~Mistaken text.~~

转为HTML后为:

<p><del>Mistaken text.</del></p>

效果:

Mistaken text.


在前面文章「CSDN-markdown基本语法说明—自动链接」中讲到,对于网址和Email的自动链接需要用一对尖括号括起来才能识别。

而在GFM中,对于标准的URL需要加链接,只需简单地输入这个URL就可以,它将被自动转换为一个链接。

例子:

http://blog.csdn.net/lanxuezaipiao/

效果:

http://blog.csdn.net/lanxuezaipiao/

但对于Email地址,在CSDN-markdown编辑器里还不支持自动识别,仍需要加尖括号。


表格

一般的表格包括表头(可选)和单元格,Markdown Extra使用竖线和分割线标记表格。

语法说明:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

第一行包含可选的表头,第二行包含位于表头和单元格内容之间的强制性分隔线,接下来的每一行就是单元格的内容,列与列之间用竖线 | 分隔。

如果愿意的话,可以在表格每一行的开头和结尾处添加竖线 |,如下所示得到的结果和上面一致:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

注意事项:

表格的每一行至少有一个竖线|,否则无法正确处理表格。这也就意味着,创建只有一列的表格,必须在每一行的开头或者结尾处添加一个竖线|,或者都添加。

例子:

项目     | 价格
-------- | ---
Computer | $1600
Phone    | $12
Pipe     | $1

转为HTML后为:

<table>
  <tr>
    <th>项目</th>
    <th>价格</th>
  </tr>
  <tr>
    <td>Computer </td>
    <td>$1600</td>
  </tr>
  <tr>
    <td>Phone</td>
    <td>$12</td>
  </tr>
<tr>
    <td>Pipe</td>
    <td>$1</td>
  </tr>
  </table>

效果:

项目价格
Computer$1600
Phone$12
Pipe$1


问题:如何设置表格对齐方式

看到这里可能有人会问:怎么都是左对齐?能不能设置为居中对齐呢?

在Markdown Extra中,需要在对应列的分隔线左右添加冒号:来指定列的对齐方式

  • 冒号 : 在分隔线的左边说明此列左对齐(默认方式)
  • 冒号 : 在分隔线的右边说明此列右对齐
  • 在分隔线的左右两边都有冒号 : 说明此列居中。

比如下面的 项目列是左对齐,价格列是右对齐,而数量列是居中对齐的:

| 项目      |    价格 | 数量  |
| :-------- | --------:| :--: |
| Computer  | 1600 元 |  5   |
| Phone     |   12 元 |  12  |
| Pipe      |    1 元 | 234  |

效果为:

项目价格数量
Computer1600 元5
Phone12 元12
Pipe1 元234


当然对于单元格里的内容,你也可以使用各种Markdown语法,比如加粗、删除线什么的。


代码块高亮

前面在文章「CSDN-markdown基本语法说明」里已经介绍了可以通过缩进四个空格或一个制表符来将文本转换为代码块,但这种方式有两个缺点:

  • 代码块的每一行都需要缩进,还好CSDN-markdown编辑器支持全选代码块然后按Tab键实现一起缩进效果,但是也有很多MD编辑器是不能这样一起缩进的,那么你就需要手动的一行一行缩进,代码长的话这将是一个费时费力且无聊的工作。

  • 不支持代码高亮功能,这对程序员来说是非常不好的体验。

幸好,CSDN-markdown编辑器经过PageDown扩展后,支持GFM的代码块高亮功能。只要把代码块包裹在 ``` 之间,你就不需要通过无休止的缩进来标记代码块了。

语法说明:

使用``` (三个反引号)包围代码块即可,里面的代码块不需要任何缩进。这种方式也称“围栏式代码块”,如下:

```
代码块
```

例子:

```
printf("Hello World!");
```

转为HTML后为:

<pre>
    <code>printf("Hello World!");</code>
</pre>

效果:

printf("Hello World!")

注意上面是默认的代码块着色效果,GFM还有更进一步的措施,你可以指定一个可选的编程语言标识符(比如c++、Java、Python等),然后就可以启用指定语言的语法着色了。

例子:

下面以一段 Ruby 代码着色为例:

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

转为HTML后为:

<pre class="prettyprint">
    <code class="language-ruby">
    require 'redcarpet' 
    markdown = Redcarpet.new("Hello World!")
    puts markdown.to_html
   </code>
</pre>

效果:

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

我们使用 Linguist 来进行语言识别和语法着色。你可以在 语言 YAML 文件 中查证哪些语言标识符是有效的。


定义列表

有时候我们在写文档时需要对某些列表项进行说明性定义,在html中我们可以使用<dt><dd>这样的标签来实现,Markdown Extra中更加简洁,只需使用冒号就可以解决。

语法说明:

列表中的项目
:  项目的定义部分

即使用“冒号:+ 一个以上的空格 + 项目的定义部分”来定义一个项目的定义内容。

例子:

项目1
项目2
:   定义 A
:   定义 B

项目3
:   这个定义有一个代码块

        代码块

项目4
:   这个定义有一个引用块

    > 定义D内容

转为HTML后为:

<dl>
  <dt>项目1</dt>
  <dt>项目2</dt>
  <dd>
    定义A
  </dd>
  <dd>
    定义B
  </dd>
  <dt>项目3</dt>
  <dd>
    这个定义有一个代码块
    <pre><code>代码块</code></pre>
  </dd>
  <dt>项目4</dt>
  <dd>
    这个定义有一个引用块
    <pre><code>定义D内容</code></pre>
  </dd>
</dl>

效果:

项目1 项目2
定义 A
定义 B
项目3

这个定义有一个代码块

代码块
项目4

这个定义有一个引用块

定义D内容


注意事项:

定义的内容可以包含行级(如行内代码)和块级(如区块引用、代码块)的Markdown语法。


脚注

脚注用于为正文中的某个条目添加补充注释,说明该条目的引文出处,跟参考文献一样,脚注一般位于文档的末尾,文章内以数字标注。在Markdown Extra也可以很容易的实现脚注。

语法说明:

在需要标记脚注文字的后面添加一个方括号,方括号中的内容必须以^开头,再接着是数字或字符串标记:

脚注[ ^1]有一个标签[^label]和该标签的定义[^!DEF].

接着,在文件的任意地方,你可以把这个脚注的内容定义出来:

[ ^1]: 这是一个脚注
[^label]: 这是脚注的标签
[^!DEF]: 这是脚注标签的定义

脚注内容定义的形式:

  • 前面引用脚注的标签符号
  • 接着一个冒号
  • 再接着一个以上的空格或制表符
  • 最后是脚注定义的内容。

脚注定义的内容可以包含多行、代码区块、区块引用和大多数其他markdown格式的内容。

例子:

这是一个脚注[ ^footnote].

[ ^footnote]: 脚注定义内容的第一行内容.
定义内容的第二行.
> 一个包含多行的
> 区块引用.

转为HTML后为:

<p>这是一个脚注<a href="#fn:footnote" id="fnref:footnote" title="See footnote" class="footnote">1</a>.</p>

<div class="footnotes">
<hr>
<ol>
<li id="fn:footnote">脚注定义内容的第一行内容. <br />
定义内容的第二行.
<blockquote> 一个包含多行的 <br />
    > 区块引用.
</blockquote> 
<a href="#fnref:footnote" title="Return to article" class="reversefootnote">↩</a></li>
</ol>
</div>

效果:

这是一个脚注1.



默认情况下,脚注内容位于生成的 HTML 文档末尾,上面的脚注内容在该文章的末尾可以看到。


自动生成目录

在需要目录出现的地方(一般在文章一开始)放置一个标记,这样会自动生成一个嵌套的包含所有标题的列表。默认的标记是[TOC]

例子:

[TOC]

# 概述

## 定义

## 用处

# 结论

最前面的那个目录就是用 [TOC]生成的。

参考资料


  1. 脚注定义内容的第一行内容.
    定义内容的第二行.
    一个包含多行的
    区块引用.
 类似资料: