Learn X in Y Minutes 教程精讲:Textile 轻量标记语言完整语法指南

原创2026-10-09 17:09:071,900 阅读
文章标签:文档教程

Learn X in Y Minutes 教程精讲:Textile 轻量标记语言完整语法指南

Textile 是一种轻量级标记语言,用简洁的文本格式语法把纯文本转换为结构化 HTML,语法是 HTML 的"速记版",易读易写。本篇以 learnxinyminutes-docs 仓库中的 textile.md 为骨架,系统讲解 Textile 的注释、段落、标题、文本样式、列表、代码块、链接、图片、脚注、表格、字符转换与 CSS 等全部语法,并逐条给出对应的 HTML 输出与实战要点。读完本文,你将能够用 Textile 直接撰写文章、论坛帖子、README 文档,并能把任意一段 Textile 文本"翻译"为标准的 HTML 结构。

一、Textile 是什么:定位与适用场景

Textile 是一种轻量级标记语言(lightweight markup language),它使用文本格式化语法,将纯文本转换成结构化的 HTML 标记。它的定位是 HTML 的速记版本(shorthand version of HTML),设计目标就是易于阅读、易于书写。正如 textile.md 开头所述,Textile 被广泛用于撰写文章、论坛帖子、README 文档,以及任何发布在网上的书面内容。

与同类标记语言相比,Textile 有几个鲜明的设计取向:

  • 块元素与行内元素分工明确:段落(p.)、标题(h1.~h6.)、引用(bq.)等块级结构与 *强调*、_斜体_、@行内代码@ 等行内样式各有独立语法;
  • 标点符号即语法:星号、下划线、方括号、圆括号、引号、感叹号分别承担不同的格式化职责;
  • 自动字符转换丰富:弯引号、省略号、破折号、分数、版权/商标符号等都会在解析时自动转换。

在本仓库中,Textile 教程遵循 CONTRIBUTING.md 定义的写作规范:文章以"示例优先于解释"为原则、代码块尽量控制在 80 字符以内、文件使用 UTF-8 编码,并通过 YAML frontmatter 声明 name、contributors、filename 等元数据(frontmatter 的解析与校验逻辑可参考 lint/frontmatter.py)。textile.md 自身的 frontmatter 即声明了 filename: learn-textile.textile,这也是该教程在网站上的可下载示例文件名。

二、快速上手:一篇 Textile 文档的基本形态

一篇 Textile 文档由若干块元素(block element)组成,块与块之间用空行分隔。大部分块元素使用"标签缩写 + 句点"的写法声明,例如 p.(段落)、h1.(一级标题)、bq.(引用)、bc.(代码块)。解析器遇到新块元素或空行,即认为前一个块结束。

h1. Textile 示例

p. 这是第一个段落,Textile 会把它包裹进 <p> 标签。

p. 这是第二个段落。

对应 HTML:

<h1>Textile 示例</h1>
<p>这是第一个段落,Textile 会把它包裹进 &lt;p&gt; 标签。</p>
<p>这是第二个段落。</p>

注意 p. 中的 HTML 标签字符会被自动转义(详见"字符转换"一节),因此你在 Textile 里可以放心书写 <、>、&。

三、注释:###. 与 ###..

Textile 支持两种注释语法,均以三个井号 ### 开头:

  • 单块注释 ###.:三个 # 加一个句点。注释可以跨越多行,直到遇到空行结束;
  • 多块注释 ###..:三个 # 加两个句点。注释内的空行也会被保留,注释一直持续到下一个块元素出现才结束。

原文示例(注释行不会输出到 HTML):

###. Comments begin with three (3) '#' signs followed by a full-stop period '.'.
Comments can span multiple lines until a blank line is reached.

###..
Multi-line comments (including blank lines) are indicated by three (3) '#'
signs followed by two (2) full-stop periods '..'.

This line is also part of the above comment.

The comment continues until the next block element is reached

p. This line is not commented

此外,标准的 HTML 注释 <!-- ... --> 在 Textile 中同样被识别并保留。

实战要点:###. 适合注释单段落说明文字;当需要在源码中"藏"一大段含空行的说明、又不想让空行打断注释时,使用 ###..,并用下一个块元素(如 p.)显式结束注释。

四、段落与块元素:对齐、缩进、引用与预格式化文本

4.1 段落的基本规则

段落由一行或多行相邻文本构成,段落之间用一个或多个空行分隔。也可以使用 p. 显式声明段落。段落内不带空格的换行等价于 XHTML 中的 <br />;而以空白字符开头的行不会被包裹进 <p>..</p> 标签。

This is a paragraph. I'm typing in a paragraph isn't this fun?

Now I'm in paragraph 2.
I'm still in paragraph 2 too!
Line breaks without blank spaces are equivalent to a <br /> in XHTML.

p. I'm an explicitly defined paragraph

 Lines starting with a blank space are not wrapped in <p>..</p> tags.

4.2 块元素对齐:<、>、=、<>

段落(以及所有块元素)都可以使用缩写进行对齐,写法是标签缩写后紧跟对齐符号:

写法 含义 等价 HTML
p<. 左对齐(默认) <p style="text-align:left;">
p>. 右对齐 <p style="text-align:right;">
p=. 居中 <p style="text-align:center;">
p<>. 两端对齐 <p style="text-align:justify;">
h3>. 右对齐的 <h3> <h3 style="text-align:right;">
p<. Left aligned paragraph (default).

p>. Right aligned paragraph.

p=. Centered paragraph.

p<>. Justified paragraph.

h3>. Right aligned <h3>

4.3 缩进:圆括号 ( 与 )

段落可以用圆括号实现缩进,每个括号代表 1em,缩进通过 padding-left / padding-right CSS 样式实现:

p(. Left indent 1em.

p((. Left indent 2em.

p))). Right indent 3em.

h2). This is equivalent to <h2 style="padding-right: 1em;">..</h2>

4.4 引用块:bq.

引用块使用 bq. 标签:

  • bq. 单块引用:引用内容到空行结束;
  • bq.:URL:在句点后紧跟冒号和 URL,可附带引用来源链接;
  • bq.. 多行引用:可包含空行,持续到新的块元素出现;
  • 引用内还可以直接嵌入 HTML 的 <footer> 标签来添加引用出处文字。
bq. This is a block quote.

bq.:http://someurl.com You can include a citation URL immediately after the '.'

bq.. Multi-line blockquotes containing

blank lines are indicated using two periods

p. Multi-line blockquotes continue until a new block element is reached.

bq. You can add a footer to a blockquote using html:
<footer>citation text</footer>

4.5 预格式化文本:pre. 与 pre..

预格式化文本保留原始空白(包括行首空格),适合展示对缩进敏感的 ASCII 艺术或版式内容:

pre. This text is preformatted.  <= those two spaces will carry through.

pre.. This is a multi-line preformatted…

…text block that includes blank lines

p. End a multi-line preformatted text block with a new block element.

pre. 之后的两个空格会原样保留输出;pre.. 多行版本可包含空行,用新块元素结束。

五、标题:h1. ~ h6.

要生成 HTML 的 <h1> 到 <h6> 元素,只需在文本前加上 h#.,其中 # 是 1~6 的级别数字。标题之后必须跟一个空行。

h1. This is an <h1>

h2. This is an <h2>

h3. This is an <h3>

h4. This is an <h4>

h5. This is an <h5>

h6. This is an <h6>

标题同样支持前文所述的块级对齐语法,例如 h3>. 生成右对齐的 <h3>。标题在文档结构中承担层级语义,建议从 h1. 开始逐级向下,避免跳级,以便于目录生成与 SEO 解析。

六、简单文本样式:强调、斜体、上下标、增删与引用

Textile 的行内样式全部围绕特定符号展开,且强调类样式区分了语义级别:

6.1 粗体与加强(* 星号)

  • *文本*:<strong> 强调(strong);
  • **文本**:<b> 粗体(bold);
  • 词内标记:This is [*B*]old text within a word.。

*Strong* 与 **Bold** 在浏览器中显示效果通常相同,但生成的 HTML 标记不同(<strong> vs <b>),语义上有区别:<strong> 表示"重要",<b> 仅表示"视觉加粗"。

*This is strong text*
**This is bold text**
This is [*B*]old text within a word.

*Strong* and **Bold** usually display the same in browsers
but they use different HTML markup, thus the distinction.

6.2 斜体与强调(_ 下划线)

  • _文本_:<em> 强调文本(emphasized);
  • __文本__:<i> 斜体(italics);
  • 词内标记:This is It[_al_]ics within a word.。

与粗体同理,_Emphasized_ 与 __Italics__ 显示效果相近,但分别生成 <em> 与 <i>。

_This is Emphasized text_
__This is Italics text__
This is It[_al_]ics within a word.

_Emphasized_ and __Italics__ text typically display the same in browsers,
but again, they use different HTML markup and thus the distinction.

6.3 上标与下标(^ 与 ~)

上标用脱字符 ^,下标用波浪号 ~,注意符号两侧需要留空格:

Superscripts are 2 ^and^ to none, but subscripts are CO ~2~ L too.
Note the spaces around the superscripts and subscripts.

To avoid the spaces, add square brackets around them:
2[^and^] and CO[~2~]L

如果不想在上下标两侧留空格,就用方括号把 ^...^ 或 ~...~ 包起来:2[^and^]、CO[~2~]L。典型应用是化学式(如 CO₂)与数学表达式(如 2ⁿ)。

6.4 删除与插入(- 与 +)

  • -文本-:<del> 删除文本;
  • +文本+:<ins> 插入文本。
This is -deleted- text and this is +inserted+ text.

6.5 引用标注(??)

用双重问号 ??文本?? 表示引文(citation):

??This is a cool citation??

七、列表:无序、有序、续号与定义列表

7.1 无序列表(*)

用星号 * 表示层级,星号越多层级越深,对应嵌套的 <ul>/<li>:

* Item
** Sub-Item
* Another item
** Another sub-item
** Yet another sub-item
*** Three levels deep

7.2 有序列表(#)

用井号 # 表示有序列表:

# Item one
# Item two
## Item two-a
## Item two-b
# Item three
** Mixed unordered list within ordered list

## 生成二级编号(Item two-a、Item two-b),且可以在有序列表中混入 * 无序子项。

7.3 自定义起始编号与续号

  • #5 让编号从 5 开始(<ol start="5">);
  • 隔一个块之后,用 #_ 让编号"接续"之前的列表继续递增。
#5 Item 5
# Item 6

additional paragraph

#_ Item 7 continued from above
# Item 8

7.4 定义列表(- 与 := / =:)

定义列表用减号 - 开头,条目与定义之间用 := 连接;多行定义用 := 开始、=: 结束:

- First item := first item definition
- Second := second def.
- Multi-line :=
Multi-line
definition =:

对应 HTML 为 <dl>、<dt>、<dd> 结构。

八、代码块:bc. 与行内代码 @

代码块使用 bc. 速记(block code):

bc. This is code
    So is this

This is outside of the code block

bc.. This is a multi-line code block

Blank lines are included in the multi-line code block

p. End a multi-line code block with any block element
  • bc. 单块代码:bc. 之后的行是代码,代码块内的相对缩进会被保留;后续空行后回到普通文本;
  • bc.. 多行代码:可包含空行,用任意块元素结束;
  • 行内代码用 @ 包裹:@inline code@,生成 <code>inline code</code>。
p. Indicate @inline code@ using the '@' symbol.

实战要点:与 pre. 预格式化文本不同,bc. 的语义是"代码",在输出为 HTML 时通常搭配 <pre><code> 结构,便于语法高亮;而 pre. 保留一切空白字符,适合展示对空白敏感的文本。

九、水平分隔线:--

两条连字符 -- 即可生成 <hr/>:

--

注意与"字符转换"一节中的长破折号 --(em dash)区分:独占一行、两侧无其他文本的 -- 被解析为水平线,而句子中间的 -- 会被转换为长破折号。

十、链接:引号、命名链接与方括号

10.1 基本链接

链接文本放在引号中,后面跟冒号和 URL:

"Link text":http://linkurl.com/ plain text.

生成 <a href="http://linkurl.com/">Link text</a>。

10.2 带标题属性的链接

标题放在链接文本末尾的圆括号中:

"Titles go in parentheses at the end of the link text"(mytitle):http://url.com

生成 <a href="http://url.com" title="mytitle">Titles go in parentheses at the end of the link text</a>。

10.3 方括号消歧

当链接文本或 URL 本身可能产生歧义(例如 URL 内含圆括号)时,把整个链接用方括号括起来:

["Textile on Wikipedia":http://en.wikipedia.org/wiki/Textile_(markup_language)]

10.4 命名链接(引用复用)

同一 URL 被多次引用时,可以先用方括号定义名字,之后用 "文本":名字 反复引用:

Multiple "references":txstyle to the "txstyle":txstyle website.

[txstyle]https://txstyle.org/

定义行 [txstyle]https://txstyle.org/ 本身不输出到页面,它只是把名字 txstyle 绑定到 URL,供后续引用使用——这类似于 Markdown 的引用式链接,能显著减少重复 URL 的维护成本。

十一、图片:!URL!

图片用感叹号 ! 包裹 URL:

  • !http://imageurl.com!:仅图片;
  • !http://imageurl.com(image alt-text)!:圆括号内是替代文本(alt text);
  • !http://imageurl.com(alt-text)!:http://image-link-url.com:图片本身作为链接,冒号后是点击跳转的 URL。
!http://imageurl.com!

!http://imageurl.com(image alt-text)!

!http://imageurl.com(alt-text)!:http://image-link-url.com

实战要点:始终为图片补充 alt 文本(第二个圆括号参数),这既是无障碍访问的要求,也有助于搜索引擎理解图片内容;第三种写法把"展示图片 + 点击跳转"合二为一,适合文章封面图或缩略图。

十二、脚注与尾注:fn、note 与 notelist

Textile 提供了完整的脚注(footnote)与尾注(endnote)体系,适合学术引用或长文注释。

12.1 数字脚注(fn)

  • 正文中用方括号写引用编号 [1];
  • 脚注文本用 fn1. 声明,内容中仍可使用链接等行内语法;
  • [2!] + fn2. 生成不带反向链接的脚注;
  • [3] + fn3^. 生成带反向链接(从脚注跳回正文)的脚注。
A footnote is indicated with the reference id in square brackets.[1]

fn1. Footnote text with a "link":http://link.com.

A footnote without a link.[2!]

fn2. The corresponding unlinked footnote.

A footnote with a backlink from the footnote back to the text.[3]

fn3^. This footnote links back to the in-text citation.

12.2 键值尾注(note)

尾注使用键值对:正文用 [#key] 引用,文末用 note#key. 给出尾注文本,编号自动生成(第一个出现的引用为 1,依此类推);[#key!] 表示该尾注不被正文链接。

Endnotes are automatically numbered[#first] and are indicated using square[#second]
brackets and a key value[#first]. They can also be unlinked[#unlinkednote!]

note#first. This is the first endnote text.

note#second. This is the second text.

note#unlinkednote. This one isn't linked from the text.

12.3 notelist:尾注列表的排版

用 notelist 块把尾注列表插入正文,并控制编号起点(数字、小写字母或希腊字母):

notelist:1. ###. start at 1 (then 2, 3, 4...)
notelist:c. ###. start at c (then d, e, f...)
notelist:α. ###. start at α (then β, γ, δ...)

notelist 还有一组修饰符控制反向链接行为与未引用尾注的展示:

写法 行为
notelist. 每个尾注带指向其全部正文引用的反向链接
notelist+. 同上,并在末尾附上未被引用的尾注
notelist^. 每个尾注只带指向第一次引用的一个反向链接
notelist^+. 同上,并在末尾附上未被引用的尾注
notelist!. 尾注不带任何反向链接
notelist!+. 同上,并在末尾附上未被引用的尾注

十三、表格:管道符、表头、行/列合并与对齐

13.1 基础表格

用管道符 | 分隔单元格,一行即一个 <tr>:

| A | simple | table | row |
| And | another | table | row |
| With an | | empty | cell |

空单元格直接留空(如 | |)。

13.2 表头 |_.

单元格以 |_. 开头即为表头单元格(<th>):

|_. First Header |_. Second Header |
| Content Cell | Content Cell |

13.3 thead 与 tfoot

在表头行上方加 |^.、下方加 |-,即可把表头行包裹进 <thead>:

|^.
|_. First Header |_. Second Header |
|-.
| Content Cell | Content Cell |
| Content Cell | Content Cell |

类似地,在页脚行上方加 |~.、下方加 |-,生成 <tfoot>:

|~.
|\2=. A footer, centered & across two columns |
|-.
| Content Cell | Content Cell |
| Content Cell | Content Cell |

注意 |\2=. 已经用到了列合并语法(见下文),并让页脚跨两列居中。

13.4 单元格 / 行 / 表格属性

  • 单元格属性写在单元格内部:|a|{color:red}. styled|cell|,其中 {color:red} 是内联样式,styled 前的 a 是……(原文示例中 a 表示属性标记位,其后紧跟 {...} 样式);
  • 行属性放在行首,以"属性 + 句点 + 空格"开头:(rowclass). |a|classy|row|,(rowclass) 表示该行应用 CSS 类;
  • 表格属性通过特殊的 table. 块修饰符写在表格之前:
table(tableclass).
|a|classy|table|
|a|classy|table|

13.5 列合并 \ 与行合并 /

  • 反斜杠 \ 用于列合并,|\2. spans two cols | 表示该单元格横跨 2 列;
  • 正斜杠 / 用于行合并,|/3. spans 3 rows | row a | 表示该单元格纵跨 3 行,后续行不再重复该单元格。
|\2. spans two cols |
| col 1 | col 2 |

|/3. spans 3 rows | row a |
| row b |
| row c |

13.6 单元格内垂直与水平对齐

垂直对齐(写在单元格内容前):

|^. top alignment|
|-. middle alignment|
|~. bottom alignment|

水平对齐:

|:\1. |400|
|=. center alignment |
| no alignment |
|>. right alignment |

|:...| 表示左对齐,|=. ...| 居中,|>. ...| 右对齐。

13.7 与 Markdown 表格的等价写法

textile.md 特别指出,以上复杂表格语法也可以换成类似 Markdown 的简单写法得到相同结果:

Col 1 | Col2 | Col3
:-- | :-: | --:
Ugh this is so ugly | make it | stop

其中 :-- 表示左对齐、:-: 居中、--: 右对齐。这说明 Textile 的表格语法存在两种风格:完整版(管道符 + 各类修饰符)与简写版(类 Markdown 分隔行)。

十四、字符转换:自动排版魔法

Textile 内置大量自动字符转换,让排版符号"零成本"出现。

14.1 商标与版权符号

RegisteredTrademark(r), Trademark(tm), Copyright (c)

(r)、(tm)、(c) 分别转换为 ®、™、© 的 HTML 实体。

14.2 缩写词定义

在缩写词后用圆括号给出全称,即可生成 <abbr title="...">:

EPA(Environmental Protection Agency) and CDC(Center for Disease Control)

14.3 尖括号与与号自动转义

<、>、& 会被自动转义为 &lt;、&gt;、&amp;,防止原始 HTML 注入或破坏页面结构:

< => &lt;
> => &gt;
& => &amp;

14.4 省略号

三个连续句点自动转换为省略号 …:

p. Three consecutive periods are translated into ellipses...automatically

14.5 短破折号(en dash)与长破折号(em dash)

  • en dash(短):两侧带空格的单个连字符,如 Oct - Nov 2018,转换为 –;
  • em dash(长):两个连字符,带或不带空格均可,如 an em dash--used、with spaces -- which,转换为 —;
  • 单词内部的连字符(如 less-used)不会被转换。
This line uses an en dash to separate Oct - Nov 2018.

This is an em dash--used to separate clauses.
But we can also use it with spaces -- which is a less-used convention.
That last hyphen between 'less' and 'used' is not converted between words.

14.6 分数与数学符号

One quarter: (1/4) => ¼
One half: (1/2) => ½
Three quarters: (3/4) => ¾
Degree: (o) => °
Plus/minus: (+/-) => ±

(1/4)、(1/2)、(3/4)、(o)、(+/-) 分别转换为 ¼、½、¾、°、±。

14.7 乘法/尺寸符号

字母 x 分隔数字时转换为乘号/尺寸符号 ×:

p. Numbers separated by the letter 'x' translate to the multiplication
or dimension symbol '×':
3 x 5 => 3 × 5

14.8 弯引号与撇号

直引号与撇号自动转换为弯引号(智能引号)对应的 HTML 实体;若想保留直引号,用 == 包裹文本:

"these", 'these', and this'n are converted to their HTML entity equivalents.
Leave them straight using '==' around the text: =="straight quotes"==.

十五、CSS:样式、类与 ID

Textile 允许把 CSS 信息直接附着在块元素或行内元素上:

  • 内联样式用花括号 {}:p{color:blue}. 给段落加 color: blue;
  • CSS 类用圆括号 ():p(my-class). 给段落加 class="my-class";
  • ID 用圆括号加井号 (#...):p(#my-id). 给段落加 id="my-id"。
p{color:blue}. CSS Styles are enclosed in curly braces '{}'
p(my-class). Classes are enclosed in parenthesis
p(#my-id). IDs are enclosed in parentheses and prefaced with a pound '#'.

三种修饰符可以组合使用,例如 p(my-class#my-id){color:red}. 同时指定类、ID 与内联样式,渲染为 <p class="my-class" id="my-id" style="color:red;">。这与前文"块元素对齐/缩进"(p>.、p((.)同属块级修饰体系,可以叠加出丰富的排版效果。

十六、Spans 与 Divs:行内与块级容器

  • span:用百分号 % 包裹行内内容,%spans% 生成 <span>spans</span>,常与 CSS 类/样式组合使用(如 %{color:red}重要内容%);
  • div:用 div. 速记声明块级容器,div. 之后的内容包裹进 <div>,同样支持类、ID、样式与对齐修饰。
%spans% are enclosed in percent symbols
div. Divs are indicated by the 'div.' shorthand

从源码结构看,% 与 div. 是 Textile 提供"语义容器"的两种手段:需要行内包装用 span,需要块级布局用 div,二者都可承载第 15 节的 CSS 修饰符,是构建复杂页面布局的基础。

十七、写作规范与仓库约定

作为本仓库的教程文档,textile.md 遵循 CONTRIBUTING.md 的通用规范:行宽尽量不超过 80 字符、示例优先于解释、文档整体保持简洁可扫读;文件头部使用 YAML frontmatter 声明元数据(name、contributors、filename),仓库的 lint/frontmatter.py 会校验 frontmatter 的键名、类型与 YAML 合法性。参照 textile.md 的格式撰写新的语言/工具教程,是最快上手本仓库贡献流程的方式。

十八、总结与进阶方向

Textile 的核心优势可以概括为三点:

  1. 块级语法丰富:段落、标题、引用、预格式化、代码块、各类列表、表格一应俱全,且每个块元素都支持对齐、缩进、CSS 修饰;
  2. 行内语法直观:强调/粗体、斜体、上下标、删除/插入、引文、链接、图片、行内代码,全部由标点符号承担;
  3. 自动排版贴心:弯引号、省略号、破折号、分数、商标符号、HTML 实体转义等自动完成,作者可以专注于内容本身。

进阶使用时,可以把多种语法组合:例如在表格单元格内使用 {color:red} 样式、在引用块内嵌入链接与脚注、用 notelist 管理长文尾注、用命名链接统一维护重复 URL。无论你是要撰写在线文章、论坛帖子还是项目 README,Textile 的这套"HTML 速记"语法都能帮你以更低的书写成本产出结构严谨、排版美观的 HTML。

登录后查看全文
learnxinyminutes-docs