reStructuredText Intro

Kana

我看着 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	:: one two bullet and - * + could be used	same, same.
Images	`![alttext](link)`	.. image:: link :alt: alttext

使用：

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

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

.. csv-table::

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

    .. code:: python

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

显示出来就是这个样子：

第一行第一列

示范一个内嵌代码块：

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

在文章里找个地方放下：

.. sectnum::

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

支持的有 attention, caution, danger, error, hint, important, note, tip, warning ，例如：

.. note::

    这样渲染起来会是这个样子。

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

.. TEASER_END

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