MDwiki 官方文档选择性翻译

MDwiki 可以将你的 md 文档发布到静态网站，由前端渲染成网页。

为了将 md 笔记发布成静态网站，且无需将 md 文档转换成 html 文件，会要用到这个工具。但英文文档看着头疼，所以把其中需要的部分翻译出来。

关于

MDwiki 是一个 CMS / Wiki 系统，完全基于 HTML5 / Javascript ，可在 100％的客户端上运行。 不需要特殊的软件安装或服务器端处理。 只需将 MDwiki 附带的 mdwiki.html 上传到与 markdown 文件相同的目录中，就可以使用了！

Features

• 完全在 Javascript / HTML5 基础上建构，不需安装任何软件
• 使用 Markdown 作为其输入标记语言
• 在 jQuery 和 Bootstrap3 之上构建，具有响应式布局，以跨浏览器工作。
• 使用带 Gimmicks 的扩展 Markdown 语法以增加客户端功能，例如通过 hightlight.js 高亮语法、 GitHub Gists 或 用 Google Maps 获取地理数据
• 可通过 Bootstrap 进行主题更换，支持 bootswatch 中的所有主题

Requirements

• web server
• 任何新一点的浏览器
• mdwiki.html 文件

如何工作？

只需将下载页面上的 mdwiki.html 以及 markdown 文件放到某个网站空间中即可。 您可以在井号＃！之后将任何网址（相对于 mdwiki.html 文件）传递给 mdwiki：

http://www.example.com/mdwiki.html#!myfile.md

如果将 mdwiki.html 重命名为 index.html ，则可以在大多数 Web 服务器上省略文件名：

http://www.example.com/#!myfile.md

默认情况下，MDwiki 将在与 index.html 相同的目录中加载一个名为 index.md 的文件，因此，如果您使用 index.md 文件作为入口点，那么您要做的就是输入域名：

http://example.com/

特别鸣谢

如果不是以下这些出色的软件，则 MDwiki 将不会存在：

• marked
• jQuery
• Bootstrap
• Bootswatch
• colorbox
• highlightjs

MDwiki 由 Timo Dörr 创建。 Follow @timodoerr.

License

GNU GPLv3 with additional terms applied.

文档

快速开始

Markdown

一个 index.md 长这样：

Heading
=======

SubHeading
----------

  * list item 1
  * list item 2

  This is a hyperlink to [Google](http://google.com).

  Images are like hyperlinks, but with an exclamation mark in front of them:
  ![](http://placekitten.com/g/250/250)

MDwiki 使用 GitHub flavored markdown dialect ，可以加表格：

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

详见 GitHub Markdown Cheatsheet

制作一个网站

您要做的就是上传带有 .md 文件扩展名的 markdown 文件以及 mdwiki.html，并通过 #! 访问它们！ 例如：

http://example.com/mdwiki.html#!myfile.md

建议您创建一个 index.md 文件，当不指定任何参数时，该文件将作为 Wiki 的起点。在这种情况下，MDwiki 将自动获取并显示 index.md 。 如果您也将 mdwiki.html 文件重命名为 index.html ，则不需要任何参数，并且可以在 http://example.com/ 上访问 Wiki！

添加一个导航

在 mdwiki.html 同级目录创建一个 navigation.md ，并放入组成菜单的链接：

# Your wiki name

[Home](home.md)
[About](about.md)
[Download](download.md)

第一行是 Markdown 标题，它将用作导航栏中的网站名。 导航栏条目使用标准 Markdown 链接。

对于更复杂的菜单，也可以将子菜单项嵌套为列表，并使用水平线分隔：

# Brand name

[Menu Item 1]()

  * # SubMenu Heading 1
  * [SubMenu Item 1](subitem1.md)
  * [SubMenu Item 2](subitem2.md)
  - - - -
  * # SubMenu Heading 2
  * [SubMenu Item 3](subitem3.md)
  - - - -
  * # SubMenu Heading 3
  * [SubMenu Item 3](subitem3.md)

[Menu Item 2](item2.md)
- - - -
[Menu Item 3](item3.md)

如果如上例中那样，为列表中的链接提供了项目符号，则该列表将成为导航栏中显示子菜单的下拉列表。 为了使它起作用，顶级链接必须有一个空目标（请参阅上例中的 Menu Item 1 ）。 下拉标题也可以通过在前面加一个 ＃ 来实现。

创建链接

略

图像

![](http://placekitten.com/g/1200/300 "A kitten")
![](http://placekitten.com/g/550/450 "First of two kittens")
![](http://placekitten.com/g/550/450 "Second of two kittens")
![](http://placekitten.com/g/400/350)
![](http://placekitten.com/g/400/350)
![](http://placekitten.com/g/400/350)

图像作为链接

[![ImageCaption](path/to/image.png)](http://www.linktarget.com)

Example:
[![A kitten](http://placekitten.com/g/400/400)](http://www.placekitten.com)

代码高亮

MDwiki 支持 GFM 之类的语法的突出显示。 将语言名称放在代码块中的反引号后面：

```javascript
var hello = function () {
    // say hello
    alert('Hello world!');
}

会显示成：

```javascript
var hello = function () {
    // say hello
    alert('Hello world!');
}

目前支持以下语言：

Gimmicks

通过使用 Gimmicks（类似于插件），可以在 Wiki 中添加更多动态元素，并以非常高级的方式使用它。 有关完整参考，请参见 Gimmicks 页面。

布局

所有页面均应以第一个标题开头，该标题将变为页面标题。 要将页面分为几个区域，请使用 2 级标题。 所有 2 级标题将最终显示在侧边菜单中以进行页内导航：

Heading
=======

Section 1
---------

[...]

Section 2
---------

[...]

图片浮动

标准 Markdown 无法用浮动图片影响最终网站的布局。 为了使能做浮动图片，MDwiki 以一种特殊的方式来解释图像和段落之间是否存在空白行，从而使文本像报纸一样自适应。

图片浮到左边

如果将图像放置在段落的顶部，并且图像和段落之间没有任何空白行，则图像将向左浮动。

![](http://placekitten.com/g/800/800)
The above image floats left to this text.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.

图片浮到右边

如果将图像放置在段落的底部，并且图像和段落之间没有任何空白行，则图像将向右浮动。

The images below float right to this text.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
![](http://placekitten.com/g/600/600)
![](http://placekitten.com/g/600/600)

没有浮动

图像前后的空白行会禁用任何浮动。

![](http://placekitten.com/g/600/350)
![](http://placekitten.com/g/600/350)

This text is preceded by two images, that span across the whole Page width.

FAQ

• 问：能否从浏览器菜单或通过 file：// URL 指定在中打开 mdwiki.html？
• 答：可以，至少对于大多数浏览器而言。 有些 gimmicks 在某些浏览器上无法使用。 以下是通过 file：// 打开 MDwiki 的浏览器支持情况：
  • Firefox (v23): 运行良好，没有已知问题。
  • Internet Explorer (v10): 运行良好，没有已知问题。
  • Google Chrome: 仅在以命令行参数--allow-file-access-from-files 启动时才有效。 即使如此，Chrome 仍然存在一些小问题。 即 数学头将无法正确呈现。
  • Safari: 不能用。 可能需要在 Chrome 中使用 cmdline 标志？

使用 file:// 链接时以下 Gimmicks 不会工作:

• Facebok Likebutton (problem with their Cross-Origin setting?)
• Disqus (hardcoded //-prefixed urls in their scripts)

• 问：我不想在本地安装 nginx 或 apache 。 设置本地 HTTP 服务器以开始使用 MDwiki 最快/最简单的方法是什么？

• npm install -g http-server
  http-server
  

  两者都将侦听本地计算机上的端口 8080。

• 问：可以通过 Google 等搜索引擎对 MDwiki 生成的网站进行爬网和建立索引吗？
• 答：可以，但需要一些额外工作。 目前尚无对用户友好、简单的解决方案，但我们正在努力。 以 [www.notesync.org] 为例，该网站正在运行 MDwiki，并已由 Google 完全索引。 我们仍在评估最佳解决方案，以使每个人都可以轻松使用相同的技术。

自定义

主题选择器

有一个 gimmick ThemeChooser 可以加在导航栏添加选择主题的子菜单，通过添加下述语句：

[gimmick:themechooser](Choose theme)

到 navigation.md (或者单独每个页面) 开启

选择主题

如果没有用 ThemeChooser gimmick 设定默认主题，你可以手动指定一个主题：

[gimmick:theme](flatly)

要设定全局主题，请将下述语句：

[gimmick:theme (inverse: true)](flatly)

添加到 navigation.md 。

注意：只有默认的 bootstrap 主题被打包到了 MDwiki，可以离线使用。其他主题需要网络连接，以动态加载。

配置

你可以在 mdwiki.html 同级目录新建一个 config.json 配置文件。它必须是有效的 json 文件。目前这些选项是可用的：

• "useSideMenu": false - 关闭测边导航栏

• "lineBreaks": "original" - 不使用 GFM 的换行符，而是使用 John Gruber 的换行符。

  • 文件中的换行符会被忽略，除非他的结尾带两个空格
  • 默认是 lineBreaks: "gfm"

• "additionalFooterText": ""
  

  • Can be used to add text to the copyright footer at the bottom, like custom copyright notices.
  • Example: additionalFooterText: "All content and images © by John Doe"
  • Default: "" (empty string)

• "anchorCharacter": "¶"

  • 当悬停在标题上时，章节文字会显示为一个超链接。
  • 可以使用 HTML 标识的 Unicode 符号。例如： ⚓ 会被渲染成 ⚓
  • 默认: The pilcrow (paragraph) sign: ¶

• "title": "ACME Industries Wiki"

  • 改变网页的标题
  • 默认: "MDWiki"
  • 注意 - 这个参数不会改变在谷歌搜索结果中的网页标题. 请直接编辑 mdwiki.html 来修正。 (Issue #58)

示例如下：

{
    "useSideMenu": true,
    "lineBreaks": "gfm",
    "additionalFooterText": "All content and images © by John Doe",
    "anchorCharacter": "#"
}

在未来版本中会有更多可供调节的参数。

提示：非常建议在各种情况下都创建一个空的 config.json ，以避免 404 错误，后者不会被你的浏览器缓存。有这样一个配置文件可以加速你的浏览器加载（即便是空的）

Gimmiks

Gimmiks 是一个将很多特性加入你的页面的小工具，比如你可以使用在油管视频、图像幻灯片、Facebook 点赞按钮上。

要使用 Gimmicks ，你只需要将指定的构建链接放你的 md 文件里。例如：

[](http://www.youtube.com/watch?v=RMINSD7MmT4)

Gimmicks 通过开箱即用的 JavaScript 脚本实现。一些 Gimmicks 可以添加参数调用，要定义他们的行为：

[gimmick:ForkMeOnGitHub ({ color: 'red',  position: 'left' })](http://www.github.com/Dynalon/mdwiki)

所有参数会被解析成一个 JavaScript 对象，但为了方便，你可以省略大括号， gimmick: 最后的名字也是大小写不敏感的：

[gimmick:forkmeongithub(color: 'red', position: 'left')](http://www.github.com/Dynalon/mdwiki)

注意：Gimmiks 一般都会从网上载入动态的脚本和样式表，所以没有网的时候可能用不了。

可用的 Gimmiks

提醒

当你使用一个特殊的触发词开始一个段落，就会触发提醒，触发词必须以 : 或 ! 结尾。

触发词大小写不敏感，必须是如下语句：

Github Gists

通过传递数字 ID，可以嵌入 Github Gists：

[gimmick:gist](5641564)

Facebook 点选按钮

例子：

[gimmick:FacebookLike](http://www.facebook.com)

Arguments:

• layout

  • is one of [ 'standard', 'boxcount', 'buttoncount' ]
  • defines the layout style of the like button
  • default is 'standard'

• showfaces

  • true or false
  • whether or not to show the profile images along with the comments
  • default is true

  可参考 Facebook developer page.

Fork me on Github -Ribbon

例子：

[gimmick:ForkMeOnGitHub](http://www.github.com/Dynalon/mdwiki)

[gimmick:ForkMeOnGitHub (position: 'left', color: 'darkblue') ](http://www.github.com/Dynalon/mdwiki)

Arguments:

• color
  • is one of [ 'red', 'darkblue', 'green', 'orange', 'white', 'gray' ]
  • defines the color of the ribbon
• position
  • is one of [ 'left', 'right' ]
  • defines the upper-corner position of the ribbon

谷歌地图

[gimmick:googlemaps](Madison Square Garden, NY)

[gimmick:googlemaps(maptype: 'terrain', zoom: 9, marker: 'false')](Eiffel Tower, Paris)

[gimmick:googlemaps(maptype: 'satellite', zoom: 17)](Colloseum, Rome, Italy)

Arguments:

• maptype
  • is one of [ 'terrain', 'roadmap', 'satellite', 'hybrid' ]
  • defined the type of the map
• zoom
  • Defines the zoom level of the map (default: 11)
  • The minimum/maximum zoomlevel depends heavily on the maptype. Best way to find a fitting value is just try'n'error.

由 yUML.me 支持的 UML 图表

略

数学公式

要支持公式，必须有这个语句：

[gimmick: math]()

你可以把它添加到 navigation.md

Twitter

[gimmick:TwitterFollow](@timodoerr)

Youtube

This will show the video preview on your website:
[](http://www.youtube.com/watch?v=RMINSD7MmT4)

加上文字描述，就会变成普通链接：
[Click to see an awesome video](http://www.youtube.com/watch?v=RMINSD7MmT4)

Disqus

[gimmick:Disqus](your_disqus_shortname)

图表

Adds a chart to the screen using data from your Markdown table.

Options

• labelColumn: This is a string that indicates which column will be used to label the data points. This String must be a direct match to your table header fro the column.
• dataColumns: This is an array of strings that indicated the column to be plotted. This String must be a direct match to your table header fro the column.
• canvasId: This is an ID for the generated chart. Defaults to a random number between 1-1000.
• chartOptions: This is an object that is passed to chartjs to configure its options. Refer to chartjs for documentation on available options.
• chartType: This string is the type of chart render. Bar, Line, or Radar. Defaults to Line.

| #  | Sprint          | Points | Sum | Avg  | Note |
| -  | --------        |------- | --- | ---- | ---- |
| 1  | Sprint 1        | 6      | 6   | 6.0  | |
| 2  | Sprint 2        | 6      | 12  | 6.0  | |
| 3  | Sprint 3        | 15     | 27  | 9.0  | |
| 4  | Sprint 4        | 9      | 36  | 9.0  | |
| 5  | Sprint 5        | 6      | 42  | 8.4  | |
| 6  | Sprint 6        | 9      | 51  | 8.5  | |

[gimmick:chart ({dataColumns: ['Avg'], labelColumn: "Sprint", chartType: 'Line', width: '660px', height: '300px'})]()

[gimmick:chart ({dataColumns: ['Avg'], labelColumn: "Sprint", chartType: 'Bar', width: '660px', height: '300px'})]()

目前只支持对一个表格作统计图，但可以对同一个表格做多个不同样式的图。