[翻译]gollum的wiki主页（未完成）

gollum的wiki主页

PAGE TITLES

默认的，一个页面的标题会出现在此文件的路径，, 对应于库的根目录(或页文件目录), 无附加路径 (例如 /mordor/Sauron)。

通过 CLI 自定义标题

如果你通过 --h1-title 选项启动 Gollum ，则此页面第一个 `` header 将会被使用. 因此呢, 比方说我这儿的 markdown 页面是:
# This is my title
# This is the first h1 that will be displayed
会展示为 This is my title 作为页面标题. 页面文本的第一个头会展示为 This is the first h1 that will be displayed.
这个选项比元数据语法优先级更高.

通过元数据的语法定义标题

语法规则:
注意元数据必须为此页面的首条文本.

SUBPAGES

Gollum 允许你为页面增加页头、侧边栏、页脚. 他们将大部分情况下会被多个页面之间共享。. 子页面会影响目录下以及没有自己子页面的所有网页，.
  1. 头文件被命名为 _Header.ext,  ext 是所支持的拓展格式.
  2. 侧边栏文件被命名为 _Sidebar.ext,  ext 是所支持的拓展格式.
  3. 页脚文件被命名为 _Footer.ext, ext 是所支持的拓展格式.

PAGE SANITIZATION|清洁页面

出于安全和相容性的考虑, Gollum pages 不包含自定义 CSS, JavaScript, 以及可能危险或未知的 HTML 编译文本方式. 以上提到的不支持项目将会从普通 HTML 代码中脱离. 见 Security | 安全 页面获取更多信息.

TAGS | 标签

Gollum 的标签尽量适用于其它的 markups, 特别是 MediaWiki. 最基础的语法规则是:
[[tag]]
一些标签支持缩写，被 pipe symbols 分割. 一些缩写必须在标签之前，一些缩写必须在标签之后:
  • [[prefix-attribute|tag]]
  • [[tag|suffix-attribute]]

Link tag |链接标签

这种链接标签创建一个通往资源的超级链接. 链接标签有两种形式:
  • [[linked-resource]] - 创建的链接文本必须等于资源文本
  • [[link-text|linked-resource]] - 创建的链接文本是链接到目标文本

Linking external resources |链接外部资源

例子:
  • [[http://example.com]]
  • [[link-text|http://example.com/pdfs/gollum.pdf]]
支持的 URL 协议被列于 此处.

Linking internal files (not images or pages) | 链接内部文件 (非图像、非pages)

与链接外部资源等同, 但是 URLs 必须是路径（paths）:
  • 或是相对路径, 例如 docs/diagram.png. 相对路径创建一个与当前页面相关的路径地址. 他们不能以 斜线 作为前缀.
  • 或是绝对路径, 比如 /docs/diagram.png. 绝对路径指向相对于 Gollum 库的根目录的路径. 必须以斜线作为前缀.

Linking internal images | 内联图像

与内联文件类似, 但是支持几种特殊的缩写:
  1. [[image-url|alt=text]]图像不存在时，显示文本.
  2. [[image-url|frame]] 告诉 Gollum 图像放到 ``.
  3. [[image-url|align=position]]告诉 Gollum 以给定方式对其（align）图像. 位置可以是 left, center, and right. 默认: left.
  4. [[image-url|float]]告诉 Gollum 图像浮动，文本流于其后. 选项不可以使用 align=center option. 浮动（float）、对齐（alignment）不可兼得, align=left 默认应用.
  5. [[image-url|height=value]]设置图片最大高度. 值必需有 px or em 这些单位.
  6. [[image-url|width=value]]设置图片最大宽度. 值必需有 px or em 这些单位.
所有的缩写都可以被合并，之间以pipes（|）分割.
特殊表现:
  1. [[image-url|frame|alt=text]]告诉 Gollum 图像位于 ` 并且使用alt`的文本作为其无法显示时的内容.
TODO: 默认情况下文本将填补图像周围的所有空间. 为了控制有多少标签可以作为 wiki 词汇，使用这个标签禁止或更新一个新的屏蔽，以达到新增的文本不作数的效果.
[[_]]

Linking internal pages | 内联页面

这个符号会创建一个指向 Gollum page 的链接:
[[cannonical-page-filename]]
规范页面文件名是此页面的文件名称，满足以下规则·:
  • 无拓展名.
  • 空格 (space,U+0020) 替换为短划线 (dashe, U+002D).
  • 正斜杠 (Forward slashes,U+002F)替换为短划线 (dashe, U+002D).
例子:
  • [[J. R. R. Tolkien]] 会被 J.-R.-R.-Tolkien.ext 页面替换
  • [[Movies / The Hobbit]] 会被 Movies---The-Hobbit.ext 页面替换
  • [[モルドール]]会被 モルドール.ext 页面替换
引用页面可以放在 git 库的任意位置. Gollum 会搜索它，并为第一个找到的文件作索引.

Include tag | 蕴涵标签

与链接标签不同，蕴含标签为Pages所专用 , 以特殊语法为手段将一个页面插入到另一个页面内 , 而非显示链接:
[[include:cannonical-page-filename]]

Table-of-contents (TOC) tag | TOC标签

Gollum 允许一个特殊的标签，嵌入此页的目录到页面中:
[[_TOC_]]
或设定最大检索深度
[[_TOC_|levels = 3]]
注记:
  • 他是大小写敏感的（ sensitive）, 记得使用大写字母.
  • 他也可以用于子页面.
全局 TOC 设定 (默认情况下禁用) 强制为每一个页面加入 TOC 目录. 简单的将这一行添加到 configuration file即可完成设置:
Precious::App.set(:wiki_options, { :universal_toc => true })

Escaping tags | 逃逸标签

标签需要 be displayed on a page literally（显示在同一页面上） , 前以单引号标记:
'[[tag]]

CODE BLOCKS | 代码区域

围栏式代码块（Fenced code blocks , GitHub 样式)

自然而然，所有页面受益于此语法规则. 例子:
​```
def foo
    puts 'bar'
end
​```
块必须附有三个引号表示关闭.
缩进:
  • 反引号组（ ```` ）可随意插入.
  • 反引号组（ ``` ）代码块应当在相应水平缩进. If it is indented with an additional two spaces or one tab, they will be ignored (this makes the blocks easier to read in plaintext).
  • The ending backticks must be indented at the same level as the opening backticks.

围栏式代码块（Fenced code blocks , Kramdown 样式)

自然而然，所有页面受益于此语法规则. 例子:
​~~~~~~~~
Here comes some code.
​~~~~~~~~
The block must be enclosed with three or more tildes (~).

高亮代码区域语法

这是 GitHub-风格代码块的插件. 自然而然，所有页面受益于此语法规则. 例子:
​```ruby
def foo
    puts 'bar'
end
​```
TODO: verify and update this + maybe it's time to recap (https://rubygems.org/search?utf8=%E2%9C%93&query=pygments)
如你所闻, 代码的 language/markup 紧挨着反引号组（ ``` ）. 许多 languages/markups 可以使用，怎么显示取决于 Gollum 当前用哪种高亮语法规则:
另外 , 你还可以高亮一个库中的文件. 当然, 文件上传后在浏览器内刷新, 代码片段（code snippet）也将被上传:
​```ruby:/lib/gollum/app.rb```
这里,  /lib/gollum/app.rb 会被包含在这个页面, 并根据语法规则被高亮显示.

MACROS | 巨集

除了标签外, Gollum 提供另外一种自身的文本组织方式 - 巨集. 主要不同点是:
  • Tags 都是预定义的，且不可自定义. Macros 可以被自定义，还可以创建你自己的巨集.
  • 不同的语法规则.

默认巨集

AllPages | 所有页面
  • 描述: 打印一份包含所有 wiki 页的列表.
  • 语法: <>
  • 结果 (示例): AllPagesMacroPage
GlobalTOC | 全局目录
  • 描述: 打印一份可点击的 TOC (拥有 TOC 的所有页面)
  • Syntax: <> 你还可以用: <>

Custom Macros | 自定义巨集

每一个巨集必须:
  1. Subclass the abstract Macro class.
  2. Override the render 方法.
  3. Gollum 中注册. 因此:
    • 无论是否使用--config 选项启动 Gollum ，将你的自定义 Macro class 加入config.rb 文件,
    • 或者通过 Rack 启动 Gollum ，将你的自定义 Macro class 加入config.ru file.
示例 , 看AllPages Macro的执行.
注记:
  • 如果你创建了有用的巨集 , 请考虑向gollum-lib提交一个pull request.
  • 如果你有巨集相关很棒的想法, 请考虑为gollum创建一个 issue.

DIAGRAMS |图

Sequence diagrams | 序列图

Gollum can render sequence diagrams from source on a page. 承蒙WebSequenceDiagrams的帮助. 例子:
{{{{{{ blue-modern
    alice->bob: Test
    bob->alice: Test response
}}}}}}
你可以用其他支持样式替换 blue-modern 样式. 打开下面的链接，看看哪些样式是支持的.

PlantUML diagrams

如果你安装并配置了自己的PlantUML server, Gollum can render PlantUML diagrams from source on a page. 承蒙PlantUML帮助. 例子:
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- another="" authentication="" bob:="" enduml="" pre="" response="">You can embed any of the diagram types supported by PlantUML: sequence diagrams, case diagrams, class diagrams, activity diagrams, component diagrams, object diagrams and even wireframe diagrams.

注记:


    

  • For wireframe diagrams, you must use the *@startuml* tag followed by the *salt* keyword syntax. The new *@salt* syntax is not supported. See link.
    • 

  • There cannot be empty lines inside the @startuml/@enduml block. PlantUML expects a single paragraph and adding empty lines in between will be read as multiple paragraphs.
    • 




MATHEMATICS

To enable mathematical expressions in Gollum, start it with the --mathjax option. We recommend this page to learn about the syntax.

例子:


    

  • Inline math:
\\\(2^2\\\)
    • 

  • Display math:
text $$2^2$$ \\\[2^2\\\]
    • 


By default, Gollum uses the TeX-AMS-MML_HTMLorMML config with the autoload-all extension. You can also set your own mathjax configuration with the --mathjax-config option.

注记:


    

  • When using the Org-mode markup, you will have to wrap display math blocks in #+BEGIN_HTML ... #+END_HTML blocks.
    • 




Authentication

Out of the box Gollum doesn't support user authentication. A separate project exists, OmniGollum, that adds OmniAuth for Gollum, https://github.com/arr2036/omnigollum. With OmniGollum one can add numerous OAuth providers (Github, Google, etc).

A third party guide to configure both Gollum and GollumAuth can be found here: Gollum authentication guide

评论

发表评论

热门博文