mkdwiki-用markdown来组织wiki

Github:@hit9

Email:nz2324#126.com

view source of this page

Please see mkdwiki2,that is a better one

简介

mkdwiki是一个python语言编写的基于目录的用来组织wiki的小工具.

简明地来说:

markdown source files => html files

支持与限制

  1. wiki源文件编写只支持markdown语法
  2. 有边界隔离的代码块,以及代码块的高亮
  3. 只支持utf8编码的源文件输入
  4. 模板支持.
  5. 缓存支持,程序每次只转换修改过的源文件到html
  6. 支持生成各个标题的目录
  7. 最好使用*nix环境

安装

sudo pip install mkdwiki

或者:

sudo easy_install mkdwiki

使用

mkdwiki <input-file/dir-path> -o <output-dir-path>   (转换markdown到html)
mkdwiki tpl  <output-directory>  (生成一个模板文件样板)
mkdwiki styles <output-directory> (生成一些静态css文件)

语法

  1. 总的来概括是,支持所有的Github风格的markdown语法(在github任一页面按下m键即可看到)

  2. 另外支持的语法:

    在源文件中使用%title mytitle来指明文件标题

    生成标题目录的语法: [TOC]

模板支持

使用mkdwiki tpl <some-dir>来生成一个示例模板(生在中)

mkdwiki 会把wiki源文件目录下的tpl.html文件作为模板.(即路径input-path/tpl.html)

如果没有找到tpl.html, mkdwiki会直接转换源文件到html

一个样例模板文件:

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <title>%title%</title>
        <link rel="stylesheet" href="%html_root%style.css" type="text/css" media="screen" charset="utf-8">
        <link rel="stylesheet" href="%html_root%code-style.css" type="text/css" media="screen" charset="utf-8">
    </head>
    <body>
        %content%
    </body>

其中%html_root%代表生成的html的根目录地址.(就是out-path目录下input-path目录的路径)

%content%是你的markdown源文件转换为的html

代码高亮

十分建议使用Github风格的fenced_code写法.(三个`号为界)

mkdwiki的代码高亮使用的pygments.

一些代码高亮的样式:

github style

solarizeddark style

solarizedlight style

这里还有很多:https://github.com/richleland/pygments-css ,不过需要自己调调字体样式什么的

评论

我们可以在模板中添加第三方评论系统(比如多说)的代码来实现wiki页面的评论

缓存清除

rm <input-path>/.mkdwiki.cache~

忽略的文件

mkdwiki会忽略输入目录下的.mkdwikicache~(即记录缓存的文件),还会忽略输入目录下的模板文件tpl.html

另外,如果你在那个输入目录下建立一个叫做.mkdwikiignore的文件,每行记录一个忽略文件(或一类文件比如*.mkd),mkdwiki也会忽略它

(按照文件名进行忽略)

协议

遵循BSD协议.

BUG跟踪和联系

请使用Github issues