中文开发使用注意：

区分全角、半角符号。

这是一个开源软件，主要语言是HTML。

原文链接

页面标记 Passage markup

Harlowe 是 Twine 2 的默认故事格式。通过侧边栏你可以细读你在 Harlowe 格式的故事文本中使用的标记，以及用于编写的宏。

该文档是Harlowe Wiki 的同版本文档。点击这里

基础 basics

链接 Link

链接语法（Link syntax）

Harlowe 格式的的链接语法与其它格式略有不同。在成对的非嵌套符号“[[”和“]]”之间，你可以输入链接的文本和该链接跳转到的文章；文本和链接通过“->”或“<-”隔开，箭头指向将要跳转到的文章的名称。

你也可以使用简短语句，不使用“->”或“<-”。整个文本内容会被当作链接到的文章的名称，以及该链接的名称。

使用案例

详细

链接文本（“[[”和“]]”的中间）当中有可能包含除“]”以外的任何字符。如果出现了多余的复数个箭头，则只有最终端的箭头有效。

这个句法并不是创建链接的唯一方式，还有许多的宏指令链接，比如“(link:)”宏指令就能在你的故事中制造一个更多用途的超链接。

格式 Style

格式标记（style markup）

使用案例

详细

你可以通过使用类似于“ ''//text//'' ”的标记来达到加粗斜体的效果，但符号必须对称。“ ''//text''// ”并不会有效。

可以使用宏指令“(text-style:)”，将其附加到要创建的文本hook（钩链）上，生成更多的格式。更进一步，你还可以通过 HTML 标签比如“ <mark> ”作为附加样式选项。

编码 coding

宏指令 Macro

宏标记（Macro markup）

在Harlowe中，通过写入名称、冒号和一些数值来调用宏，这些内容都包括在括号中。比如，你可以将(print:)宏指名为(print:54 )。在这个示例中，“print”是这个宏的名称，“54”是它的值。

宏的名称不区分大小写、破折号和下划线。这意味着名称中的大小写、破折号和下划线的任意组合都将被忽略。例如，你可以把(go-to:)写成(goto:)，(Goto:)，(GOTO:), (GoTo:)，(Go_To:)，(Got--o:)，(-_-_g-o-t-o:)，或者其他任何组合变体。

你可以向宏调用（macro call）提供任何形式的数据值，数字、字符串、布尔值，等等。这些值可以是任何形式，比如“ "Red" + "belly" ”是一个表达式，可以产生一个单独的字符串“Redbelly”，并可被用于任何合在一起的字符串能够使用的地方。变量也可以与宏一同使用，如果它们的内容与宏期望（expect）的一致。所以，如果“$var”包含字符串“Redbelly”，那么“(print: $var)”“(print: "Redbelly")”和“(print: "Red" + "belly")”表达的是一个意思。

另外，每个本身会产生值的宏指令（比如“(num:)”就会产生一个数字（number），“(a:)”则会产生一个数组（array））可以被嵌入其他的宏调用。“(if: (num:"5") > 2)”的“(num:)”宏就嵌套在“(if:)”宏中。

如果一个宏能够或需要被赋予多个值，可以用逗号区隔他们。你可以给“(a:)”三个数字，比如“(a: 2, 3, 4)”。最后一个值可以有一个逗号在后面，比如“(a: 2, 3, 4, )”，效果是一样的。另外，如果数据值为数组、字符串或数据集，则可以使用“...”运算符将所有值分散到宏调用中：“(either: ... $array)”将会使“$array”中的每个值分别放置在一个“(either:)”宏调用中。

变量 Variable

变量标记 （Variable markup）

在Harlowe中，可以使用“$”（用于通常变量）或“_”（用于临时变量，临时变量仅存在于一篇文章、一个hook或lambda表达式中）来设置一个变量。并且可以通过使用“(print:)”“(for:)”来打印变量内容或其中的任何其他项目。

如果只需要打印一个单一的变量，你可以在文章内容中直接输入单一的变量名称。

此外，如果变量包含一个转换指令，比如“(text-style:)”这类宏创建的转换指令，那么变量可以被附加到hook上，以便使hook应用到该转换指令：

钩链 Hooks

Harlowe语言里，hook可以用来标明某文章文本具体跨度的特殊性。它基本上由“[”和“]”以及之间的文本构成。通过宏指令可以用各种办法修改、风格化、控制和调查hook当中的文本。

诸如“[some text]”这样的hook本身没有太大意思。不过，要是你在它前面添加一个宏或是变量，那这个hook将会因附加值而改变，例如基于游戏状态隐藏它，更改文本样式，将文本移动到文章中的其他地方。

(font:)宏是众多产生特定格式的宏指令之一，它并不是数字或者字符串这样的基本数据样式。在上面的例子里，指令使hook当中的文本字体改变为黑体，而不改变其他文本。

你可以把这个指令设为变量，以便重复使用，比如：

基础的(if:)宏也是这样使用：

有关命令宏的更多信息，请依次查看每个命令的说明。

指名钩链 Named hook

指名钩链（Named hooks）

有关hook的一般介绍，请参阅他们各自的标记说明。指名钩链是一种较不常见的hook类型，具有独特的优点。指名一个hook，需要为其添加一个“nametag （名称标签）”：

（必须以英文为hook指名）

指名钩链可以被视为变量使用，在宏指令中引用指名钩链可以直接展示hook的文本内容。要做到这样，只需像写变量一样写下hook的名称，但是要用“?”而非“$”。

以上(click:)和(replace:)宏可以远程引用并改变指名钩链。这可以允许你写下一连串带有许多hook的文本，并在随后附加一些行为。

正如你所看到的，尽管有些单词被(click:)分配给不同行为，但最上面的句子仍然是可读的。

预置指名钩链（Build in names）

有四个指名钩链是预置的，分别是?Page，?Passage，?Sidebar，?Link。除了钩链以外，还可以用宏指令来改变页面中你通常无法风格化的部分。这些预置指名钩链可以配合(enchant:)实现风格化。

• “?Page”会选择页面元件（更准确地说，是<tw-story>元件），使用(background:)宏，会为你改变整个页面的背景。
• “?Passage”只会影响到当前文章的文本元件（准确的说是<tw-passage>元件）。举例来说，它能允许你改变整个文本的(text-colour:)或是(font:)，你还能将复杂的(css:)运用其上。
• “?Sidebar”会选择文章左侧包含返回/重载图标的边栏（<tw-sidebar>）。你可以使用格式宏（styling marcos）风格化它们，或使用(replace:)和(append:)插入你自己的文本。
• “?Link”会选择文章的全部链接（文章链接，以及由(link:)和其他宏创造的链接）。

（请注意，如果您为自己的hook指名为上述名称，那么理所当然你的hook会被包含进去。）

隐含钩链 Hidden hook

隐含钩链（Hidden hooks）

隐含钩链是指名钩链的进阶版本，可以通过(show:)使隐含的钩链得到揭示。若想了解指名钩链的使用方法，请参阅他们各自的标记说明。

可能有一些你不想文章一出现就能被看见的hook内容，需要延时出现，或是点击一个链接以使其出现。你可以设置一个被隐藏的hook，具体方法是修改hook的标记语句，用圆括号替换其中的“>”或者“<”。

为了利用它，隐含钩链必须有一个名称，使用(show:)这类宏使之显现。如果不使用(if:)这类条件宏，是不能设置一个没有名称的隐含钩链的。

附加项 extra

HTML

Harlowe当中，HTML标签（比如“<img>”）和HTML元件（比如“&sect;”）可以被直接插入到你的文章文本中。因为Harlowe是用HTML编写的。

使用案例

详细

这种HTML元件由Harlowe给予了一个“data-raw”属性，以区分由标记创建的元件。

你可以为文章添加“<script>”标签以运行Javascript代码。一旦包含代码的文章得以呈现，代码就会开始运行。

你还可以添加包含CSS代码的“<style>”标签。CSS会影响到整个页面的效果，直到这个元件从DOM中移除。

最后，如果你想留给自己一些关于文章代码的提示信息或者解释，你还可以在代码中添加HTML注释“<!-- Comment -->”。

Verbatim

Verbatim 标识（Verbatim markup）

由于Harlowe当中有大量符号拥有特殊作用，你可能会好奇怎样正常地使用它们，仅仅是单纯地作为符号使用，不调用特殊功能。你可以将它们放置于一对重音符“`”之间。

如果你遇到一串已经包含了“`”的文本，只需增加一对“`”，放在那两边即可。

使用案例

成对重音符可以无限使用。

列表 list

符号列表 Bulleted list

符号列表（Bulleted lists）

你可以在你的文本中创建一个点状项目列表，具体方法是起始行使用一个星号“*”，后跟空格，接下来是项目内容。星号会被一个缩进的点状符号替换。连续数行的项目符号会被视在同一个列表内，在垂直方向上均匀分布。

请注意星号和项目列表文本之间必须有空格！否则会和格式标记（强调标记）搞混。

如果你用了多个星号（“**”,“***”等等），你会创建一个嵌套列表，比正常的列表更向内。嵌套列表类似于正常列表的“孩子”。

使用案例 

数字列表 Numbered list

数字列表（Numbered list）

你可以在文本中创建一个数字列表，效果类似于符号列表，只不过用数字取代了点状符号。只需起始行用“0.”作为开始，后跟空格，再跟项目内容。连续数行的项目符号会被视在同一个列表内，在垂直方向上均匀分布。每个“0.”将会被项目中相对应的数字替换。

请注意星号和项目列表文本之间必须有空格！否则会被视为单纯的数字和符号。

如果你用了多个“0.”（“0.0.”,“0.0.0.”等等），你会创建一个嵌套列表，比正常的列表更向内，并且会重新计数。嵌套列表类似于正常列表的“孩子”。

部件 section

对齐 Aligner

对齐标记（Aligner markup）

对齐标记是一个特殊的单行标记，用于指定后续文本的对齐方式。它本质上来说是“modal”，因为标记中的所有文本都被包裹在一个<tw-align>元件中，向前处理所有的文本，直到遇到另一个对齐标记（或是在左对齐的情况下展开，因为它是默认的）。

• 右对齐，以“==>”为例，使用两个或两个以上“=”，后跟“>”。
• 左对齐，以“<==”为例，前置“<”，后跟两个或两个以上“=”。
• 两端对齐，以“<==>”为例，前后分别是“<”“>”，中间使用两个或两个以上“=”。
• 混合对齐，前置一个或一个以上“=”，后跟“><”，再跟一个或一个以上“=”。比率由左右两侧“=”的数量决定。比如，“=><===”是25%左对齐。

标记前后使用多少空格都无所谓，只要在一行就可以。

使用案例

纵列 Column

纵列标记（Column markup）

纵列标记类似于对齐标记，是一个特殊的单行标记，用于指定后续文本以纵列的形式展示。它们由多个“|”标记组成，用于指定该列相对于其他列的大小，而所有列的总体宽度等于页面宽度，且这些列按其“|”标记分列。它们还被多个“=”包围，用于在CSS“em”单元中指定该列的页边距（大概是一个大写M的宽度）。

所有纵列标记下的文本会持续向前运行，直到遇到下一个标记。“|==|”会结束纵列标记，恢复到正常页面效果。

每列会按照外观顺序从左向右排列。

标记前后使用多少空格都无所谓，只要在一行就可以。

使用案例

标题 Heading

标题标记（Heading markup）

标题标记用创建大标题，比如结构化的文章或标题画面。它与Markdown标题语法几乎相同：开始新一行，有一到六个“f#”，并以换行符结束。

使用案例

不同于Markdown，“#”前的空格数量不限。

水平线 Horizontal rule

水平线标记（Horizontal rule markup）

Hr（Horizontal rule）是一条横越文章的水平线。HTML中，它是<hr>元件。在Harlowe它是一条由三个或三个以上连字符“-”组成的线。

使用案例

同样，连字符前后的空格不限。

空白 whitespace

空白whitespace

“空白”是指用于分隔编程代码标记的空白字符，比如空格键空白或是tab制表符。它们在类型和数量上是共通的，使用两个空格通常与使用一个tab制表符效果是一样的 。

Harlowe还在尝试识别大多数的Unicode空白，包括quad，per-em，per-en空白，但是不包含零宽度空白（它们可能会导致混淆和语法错误）。

压缩空白 Collapsing whitespace

压缩空白（Collapsing whitespace）

当使用宏或是HTML标签时，为了更简便的阅读可以使用空格或是缩进。然而这样的文本也会出现在展现出来的文章文本中。你可以在这样的文本周围使用“{”和“}”符号，这当中所有成串的空白（换行、空格）将会被压缩为一个空白。

使用案例

详细

你可以为该标记使用嵌套 ，如“{好{球！}}”，但里面的那一对因为嵌套不会有任何不同的表现。

宏调用中的文本（特别是提供给宏的字符串中的文本）不会被折叠。宏调用输出的文本也不会。“{(print:" ")}”将会打印全部三个空位，“{(display:"Attic")}”也会显示名为“Attic”的文章内所有的内容。

Verbatim句法中的文本，比如“Thunder` `hound”同样不会被压缩。

如果该标记包含一个应用hook的(replace:)指令，则hook中的空白仍会被压缩，即使它要替换的文本在标记之外。

如果你只想删除特定的换行符，可以考虑使用转义换行标记。

转义换行标记 Escaped line break

转义换行标记（Escaped line breaks）

有时你也许需要写相当长的一行，可能还包括着许多宏。这样在文本编辑器中读起来可能相当麻烦。“\”符号或许会帮到你，在换行前或者换行后使用该符号将会移除换行符，使多行成为一行。

使用案例

详细

“\”之间不能有任何空白或换行符，否则该标记不会生效。

宏调用中不可使用。值当中的换行本身则就是被忽视掉的。