MDwiki 官方文档选择性翻译

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

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

关于

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

Features

Requirements

如何工作?

只需将下载页面上的 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 将不会存在:

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!');
}

目前支持以下语言:

Language 关键词
Bash bash
C# csharp
Clojure clojure
C++ cpp
CSS CSS
CoffeeScript coffeescript
CMake cmake
HTML HTML
HTTP http
Java Java
JavaScript JavaScript
JSON JSON
Markdown Markdown
Objective C objectivec
Perl perl
PHP PHP
Python python
Ruby Ruby
R r
SQL SQL
Scala scala
Vala vala
XML XML

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:// 链接时以下 Gimmicks 不会工作:



自定义

主题选择器

有一个 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": 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

提醒

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

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

Type Trigger
Warning warning, achtung, attention, warnung, atención, guarda, advertimiento, attenzione
Note note, beachte, nota
Hint hint, tip, tipp, hinweis, suggerimento

GitHub Gists

通过传递数字 ID,可以嵌入 GitHub Gists:

[gimmick:gist](5641564)

Facebook 点选按钮

例子:

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

Arguments:

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:

谷歌地图

[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:

由 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

| #  | 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'})]()

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

1 操作
HaujetZhao 在 2020-06-22 16:36:31 更新了该帖

赞助商 我要投放

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...