本文介绍如何用ditto构建wiki静态站点,发布到github pages可随时随地进行访问,ditto构建的wiki支持站内查询和在线编辑,适合搭建个人wiki。
几种wiki搭建技术的比较
在使用ditto之前我还尝试了xwiki,gollum,MDWiki,xwiki偏向企业级,当时因为丰富的扩展插件用起来会很合适,后考虑到github pages提供免费的静态站点发布以及个人wiki的简洁性,就放弃了,以后团队需要时再考虑,而gollum之所以没采用是因为我经常要在windows上维护本地wiki,在windows上直接只在github提供的wiki上操作又没有树形目录不能调整布局样式,不方便(而且gollum安装时碰到了因为gollum的默认依赖grit导致的编码问题,更换依赖为rugged后,解决部分问题,搜索依然乱码,一想,windows都不支持就不浪费时间了),放弃。MDWiki跟ditto类似,都是通过一个html来处理写作好的markdown文件,但是ditto的布局我更偏向一点,简洁而又突出内容,搭建也很简单,加上github pages就能发布到公网了。
下载ditto
执行命令 curl -L https://git.io/v6T7r > install.sh && sh install.sh
ditto相关的文件会下载到当前目录,具体包含了:
- sidebar.md
- install.sh
- index.html
- docs
sidebar.md是侧边栏,install.sh启动程序,启动会自动生成上述文件,服务器默认访问的主页面即index.html,docs有api.md和faq.md,只是例子,具体是在sidebar.md引入链接,引入链接时不用写后缀名,会自动加上的。
写作
我们在docs下面创建要写作的markdown文件,我用sublime text 3来进行markdown的写作,需装markdown相关插件
运行服务器
我在win7系统安装了python,在工程根目录下打开git bash或者其他命令行窗口执行server命令运行wiki,cmd用python.exe -m http.server 8000可开启指定端口(此处设置为8000)的服务器,方便快速查看本地效果。可用其他服务器。
部署发布
上述步骤已完成wiki的搭建和运行,现在需要部署发布到github上。
首先你得有github账号,在上面创建一个srepository,然后clone到本地,即你的本地工程,本地工程中加入,如下文件(从ditto源码中拿,源码传送):
- sidebar.md
- index.html
- js
- marked.js
- highlight.js
- ditto.js
- css
- docs
观察index.html,发现引用的js和css不是cdn就是ditto的github上的地址,我拷贝js和css到自己的工程来,保证js和css不会因为ditto更新而变化,若要更新所用ditto可自行clone后再拷贝,另,cdn的引入我改成了国内的cdn,提高访问速度。如下:
<!-- JQUERY -->
<script src="//cdn.bootcss.com/jquery/1.11.0/jquery.min.js"></script>
<script src="//cdn.bootcss.com/jqueryui/1.10.4/jquery-ui.min.js"></script>
<!-- MARKED -->
<script src="js/marked.js"></script>
<!-- HIGHLIGHT.JS -->
<link rel="stylesheet" href="css/github.css">
<script src="js/highlight.js"></script>
<script type="text/javascript"
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML">
</script>
<!-- DITTO CSS -->
<link rel="stylesheet" href="css/ditto.css">
<script src="js/ditto.js"></script>
观察sidebar.md中有个[ditto:searchbar]
这是搜索框,没有则加上,要使用搜索功能,则要在index.html中修改加载的js,设置上ditto.github_username和ditto.github_repo以及ditto.base_url,依次表示你的github用户名,github上工程仓库名(二者负责告诉ditto去github搜索页面信息进而展示在wiki上),github的页面修改地址(ditto的修改是直接跳转到github的修改链接),同时还设置了ditto.highlight_code为true,让搜索的结果代码高亮,如下
<!-- DITTO -->
<script>
$(function($) {
// essential settings
ditto.index = "README.md",
ditto.sidebar_file = "sidebar.md",
// optional settings if you want github search
ditto.github_username = "GrayOxygen"; // <------- EDIT ME!!
ditto.github_repo = "ShineOxygenWiki"; // <------- EDIT ME!!
ditto.highlight_code = true; // <------- EDIT ME!!
// where the docs are actually stored on github - so you can edit
// e.g. https://github.com/chutsu/ditto/edit/gh-pages
ditto.base_url = "https://github.com/GrayOxygen/wiki/edit/master"; // <------- EDIT ME!!
// run
ditto.run();
});
</script>
打开git bash执行git push origin master
同步到github仓库
在github的项目主页面,找到setting按钮,进入更改GitHub Pages选项,如图save后提示你已发布
save保存你所选分支后,提示已发布,wiki已发布到公网,访问吧
具体效果参考我的wiki