mokuwiki 1.0.0

注意：yaml元数据块必须以三个破折号开头，以三个句点结尾。

指令

页面中支持以下指令。这些字符通常采用双字符（通常是括号）的形式，降价处理器应该无法识别这些字符。

页面链接

如上所述，页面之间的链接使用双方括号指定，因此[[page one]]将转换为指向该标题为[page one]（page_one.html）的页面的HTML版本的标准标记链接。如果页面有别名，则可以使用别名代替标题，尽管链接名称仍基于标题：[[1st page]]变为[1st page]（page_one.html）

您还可以使用语法[[display name page one]]定义"display"名称。这将成为目标文件中的[显示名称]（page_one.html）。注意，与类似的dokuwiki语法不同，您不能在这里指定实际的文件名：它总是由"title"元数据决定。

请注意，mokuwiki假定最终输出为html，因此所有链接都以".html"结尾。

如果页面的元数据块中没有"title"字段（或根本没有元数据块），则跳过对该文件的处理。"title"也不能包含圆括号或方括号（基本上只有字母数字字符和一些标点符号）--请参阅下面关于[文件名转换]的部分。

链接到不存在的页的页链接指令将转换为带"breaked"类的括号跨距。也就是说，[[没有这样的页面]]将转换为[没有这样的页面]{.broken}。使用--broken命令行选项更改用于断开链接的类名。处理完成后，使用--report命令行选项列出标准输出上所有断开的链接（即丢失的页面）。

命名空间

页面名称可以包含对名称空间的引用，同样基于moukwiki模型，例如[[ns1:page on e]]。假定命名空间引用文件夹，因此不能包含空格。如何将它们合并到结果链接中取决于是否设置了--fullns命令行选项：

1. 如果未设置（默认设置），则假定源文件夹是主文件夹，具有单个级别的子文件夹，例如"source/ns1"、"source/n2"等。假定文件夹"source/ns1"中页面中具有命名空间引用的页面链接指向同级文件夹中的页面。因此，像"source/ns1"中文档中的[[ns2:page two]]这样的页面链接指令将转换为[page two]（../ns2/page\u two.html）

2. 当设置了--fullns时，它将把命名空间视为文件夹的完整路径。然后，作者负责指定正确的相对路径，例如[[…:..:ns2:ns3:some page]将变为[some page]（../../ns2/n3/some廑page.html）

注意：mokuwiki不会递归地处理文件夹并跟踪名称空间。此功能只会使在不同文件夹中的页面之间创建链接变得更容易。还请注意，此功能可能会在以后的版本中更改…

标记链接

可以使用以下语法在页中引用的标记：{{tag1}}。这将生成包含"tag1"标记的页面链接列表。例如，一个源片段：

Pages containing tag 'abc':

{{abc}}

可能产生：

Pages containing tags 'abc':

[Page One](page_one.html)

[Page Two](page_two.html)

标记名不能包含方括号或标点符号。在yaml块中定义时，标记名可以包含空格，例如标记：[wordy tag，other tag]。然而，W引用带有空格的标记时，必须使用下划线而不是空格，例如{{{wordy_tag+other_tag}。标记名不区分大小写。

可以使用各种运算符组合标记：

1. {{tag1 tag2}包括带有"tag1"或"tag2"的页
2. {{tag1+tag2}包括带有"tag1"和"tag2"的页
3. {{tag1-tag2}包括带有"tag1"但不具有"tag2"的页
4. {{*}包含wiki中所有具有任何标记的页面。请注意，页面不必有标记字段。
5. {{{}}表示具有任何标记的页数
6. {{tag1}表示具有标记"tag1"的页数
7. {{@}将返回源文件夹中定义的所有标记的列表，这些标记是一系列以类名称"tag"括起来的跨距。这可用于设置标记列表的样式。可以使用--tag命令行选项更改类名。

包含指令

使用以下标记将一个文件包含在另一个文件中：<；<；include\me.md>；。任何yaml数据块都将在包含之前从包含的文件中删除。此模式实际上支持全局搜索，因此您可以执行<；<；include_x*y.dat>；等操作。假定路径是相对于调用模块的目录的。

将在每个文件的内容之间插入空行，并且可以使用语法<；<；include_x*y.dat**>；在每个文件之间插入分隔符。（默认值为无分隔符，但"***"是一个有用的分隔符，因为当由pandoc处理时，它变成了一个水平规则）

通过将前缀指定为第三个"参数"，还可以在包含的文件的每个行的前面插入前缀。例如，<；<；include_x*y.dat**>；>；将在每行前面插入>；，包括文件内容作为块引号。若要在文件之间不使用分隔符，请将该参数保留为空：<；<；include_x*y.dat_124;gt；>；

图像链接

image link指令提供了一种更容易链接到图像的方法：语法！！好形象！！将转换为！[漂亮的图像]（images/a_nice_image.jpg）。注意事项包括：

1. 链接的名称（示例中的"漂亮图像"）也是图像标题的名称。
2. 默认情况下，所有图像都位于images文件夹中，该文件夹是引用文件所在文件夹的子文件夹。可以使用--media命令行选项更改文件夹名。
3. 假定默认文件格式为JPEG，因此扩展名为".jpg"。这可以使用以下语法进行更改：！！另一张图片png！！
4. Moukwiki不会检查"图像"文件夹是否存在，也不会将任何图像移动到目标文件夹。

执行指令

"exec"指令允许使用以下语法将命令的输出插入到文档中：%%ls-l test/*.dat%。命令必须在用户的路径中，并且该指令要glob的任何文件规范都必须是命令行的最后一个元素（如下所示）。支持多个分号分隔的命令。

1. 此指令使用子流程函数。因此，在使用此功能时，应牢记标准的安全注意事项。
2. 此功能尚未在Windows计算机上检查，但如果在适当的shell（例如git bash）中执行，则应该可以工作。
3. 的输出该命令应为适合标记文件的文本。

注释指令

源文件中可以包含单行注释：行中双斜杠（//）之后出现的任何字符都将被删除。没有块注释。

其他功能

单文件模式

使用--single选项可以启用单文件模式。只需要一个输入文件，命令行中给出的输出文件将按原样用于输出（即假定为预期的输出文件名）。这对于页面链接和标记不是很有用，但是对于在指定的输入文件中使用"include"和"exec"指令非常方便。在单文件模式下，[搜索索引]选项被禁用。

搜索索引

可选的命令行选项--index将导致mokuwiki输出一个json文件（称为''u index.json'），该文件包含每个页面中包含的术语相对于页面标题和文件名的反向索引。这可以用来在"wiki"中创建一个简单的搜索功能。这是json格式：

{
    "page": [
        ["page_one", "Page One"],
        ["page_two", "Page Two"]
    ],
    "abc": [
        ["page_one", "Page One"],
        ["page_two", "Page Two"]
    ],
    "one": [
        ["page_one", "Page One"]
    ],
    "two": [
        ["page_two", "Page Two"]
    ]
}

要使用<；script>；语句将其直接包含在html页面中，通常可以方便地将其声明为变量。使用--prefix选项在json前面加一个字符串。例如，作者在其中一个项目上使用了--prefix='var mw=mw{}；mw.searchindex='。

搜索索引字段

默认情况下，将分析以下yaml元数据字段以创建搜索索引："title"、"alias"、"summary"、"tags"和"keywords"。将元数据字段"noindex"设置为"true"的源文件将被索引。使用--fields选项指定不同的列表，例如--fields='title，author'

文件的内容（即正文文本，元数据之后）可以通过使用名为\u body/code>的"伪字段"进行索引。所有标点符号等都从索引项中删除。

噪音词

默认情况下，mokuwiki中包含一小部分"噪音词"。如果它们出现在任何选定的元数据字段中，则不会编制索引。可以使用--noise选项更改列表，以提供一个包含单词的纯文本文件，每行一个单词。例如，--noise=bad_words.txt

文件名转换

从"title"字段创建目标文件名，如下所示：去掉前导和后面的空格，用下划线替换剩余的空格，并使整个字符串小写。Unicode字符也会被删除。

安装

由于mokuwiki可以在pypi上找到，所以安装应该简单到：

$ pip install mokuwiki

mokuwiki依赖于pyyaml。有些单元测试依赖于deepdiff

用法

安装后mokuwiki应作为命令行脚本提供：

$ mokuwiki source-dir target-dir

或者它可以作为标准的python模块运行：

$ python -m mokuwiki source-dir target-dir

使用"mokuwiki（）"函数在python解释器中运行：

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]

---
title: Page One
alias: 1st Page
author: Phil
tags: [abc]
...

A link to [[Page Two]]