今日(きょう)(さわ)がしく(たわむ)れ生きる人々の漫画映画(まんがえいが)

reStructuredText Intro

我看着 reStructuredText 的文档绝望极了,真的比 markdown 复杂多了 T_T。我尝试着在这里做点笔记。

1 与 markdown 的比较

reStructuredText 对中文的体验极其不友好,
因为它很多结构(表格/标题)要求宽度对应,但是中文毕竟和英文跨度不同,
很多编辑器甚至处理器可能都有不同的处理方式……
不爽。
所以下面的表格用英文了。

相邻的两个块之间要用空行隔开。

/

Markdown

reStructuredText

Title

# h1
## h2
### h3
etc.
==========
  h1
==========

or:

 h2
----------

Must be wider than the text

# * = - ^ ” could be used [1]

Bold

**bold**

**bold**

Italic

*italic*

*italic*

Blockquote

> quote1
> quote2
not blockquote here
    indent and you get one
    another line
        nested another

Inline Code

`code`

``code``

Block Code

```

code
```
::

    code

Footnote 2

[1]_

and later the page:

.. [1] footnote
     could be indented

Link 2

[name](link)

link or `name <link>`_

In-page links 2

target_ or `target`_ where target could be titles, footnote, definitions, etc.

Lists

::
  1. one

  2. two

  • bullet

  • and - * +

  • could be used

same, same.

Images

![alttext](link)

.. image:: link
    :alt: alttext
A cat goes here

2 其它

2.1 生成目录

使用:

.. contents:: 目录标题
    :depth: 2

2.2 表格

一个方便的编辑表格的方法是使用 CSV 表格:

.. csv-table::

    "第一行第一列","示范一个内嵌代码块:

    .. code:: python

        a = [1, 2, 3]
        print(""No Python"")"

显示出来就是这个样子:

第一行第一列

示范一个内嵌代码块:

a = [1, 2, 3]
print("No Python")

2.3 自动章节编号

在文章里找个地方放下:

.. sectnum::

这么一行就可以了。不要放在最前面和 meta 信息混在一起,会无效。至少空一行。

3 在 Nikola 的特殊用法

因为我用的是 Nikola 这个静态博客生成系统,而在博客相关的功能方面它提供了一些特殊语法。

3.1 TEASER_END

.. TEASER_END

博客对每个页面的预览默认是不会缩短页面内容的,所以在主页等页面看到的页面预览就是完整的页面。有时页面太长了,预览最好缩短一下,这个语法标志着预览的结束(预览从页面开头一路到这个标志)。

评论