Gitit Bigger: 最好的个人Wiki/文档方案(Git、Markdown、Bootstrap、Ace、Docker)
文章略长,包括诸多环节。如果只想快速开始一个项目,请参考
Quick Start
小节。 如有改动,将会第一时间在 http://wiki.shajiquan.com/gitit-bigger 体现。
Gitit Bigger: Git and Markdown based wiki,Bootstrap, ace Editor, syntax highlight and docker deploy support.
基于 Git 和 Markdown 的超棒的 Wiki 系统,Bootstrap、Ace 编辑器等增强,支持 Docker 部署。
- Github:https://github.com/shajiquan/gitit-bigger
- DockreHub:https://hub.docker.com/r/shajiquan/gitit
- Demo: http://wiki.shajiquan.com/gitit-bigger (Read Only)
Quick Start
普通版 bigger Version
git clone https://github.com/shajiquan/gitit-bigger ~/workspace/gitit
cd ~/workspace/gitit
cp sample.gitit.conf my-gitit.conf
./run/run.sh start
Docker 版 Docker Version
docker run -d --name gitit -p 7500:7500 shajiquan/gitit
Demo
http://wiki.shajiquan.com/gitit-bigger (Read Only)
更多用法详见下文。
Gitit
一个基于 Git 版本管理系统的 Wiki,使用 Haskell 语言编写。
主要特性:
- 无数据库
- Git 版本控制
- Markdown 格式
Wiki 化:
- 子目录,无限目录(这也是我抛弃其他一些类似 wiki 系统的原因)
- 中文目录、中文标题、中文分类
- 完美支持中文搜索
- 支持分类
- 支持自定义标题
代码高亮
- 支持公式等(我基本不用)
- 导出 epub 等(基于 pandoc)
配置文件及执行流程
在任意文件夹内运行 gitit
都可以启动 gitit 服务。可以给 gitit 传递如下参数:
-p
: gitit web 服务端口号-f
: 指定一个配置文件,gitit 会解析配置文件中的port
等配置来启动服务。比如:gitit -f my-gitit.conf
。- 如果不指定,gitit 将会使用默认配置,默认配置可由
gitit --print-default-config > my-gitit.conf
获得。
- 如果不指定,gitit 将会使用默认配置,默认配置可由
在 gitit 启动服务时,它会根据配置文件来绑定 IP、端口,创建必要的文件夹、文件等。
static/
: 静态文件所在目录templates/
: 模板文件所在目录wikidata
: wiki 条目文件所在目录gitit-users
: 用户数据所在文件gitit.log
: 日志文件
以上这些项,都可以在配置文件中自定义,不过我建议使用官方默认的。以下是一些重要配置项。
重要配置项
port
: 7500 # Gitit Web Server 的端口号,官方默认是 5001,我自己用的配置是 7005。wiki-title
: Wiki # the title of the wiki.require-authentication: modify
: #授权阶段。可选none
、modify
、read
:none
: 所有阶段(编辑、浏览等)都不需要
用户登录。modify
: 编辑阶段。当用户要编辑、删除条目时,需要登录。read
:阅读阶段。当用户需要浏览条目时,需要登录。
access-question
: Who is shajiquan? # 访问控制问题。- 在创建用户时,将必须回答这个问题。答案必须是下方的
access-question-answers
中指定的答案,答案间使用英文逗号分隔。
- 在创建用户时,将必须回答这个问题。答案必须是下方的
access-question-answers
: github.com/shajiquan, https://github.com/shajiquandefault-extension
: md # 默认文件名扩展,官方默认的是page
,我自己的版本使用的是md
。注意
:这个只在 Gitit 0.11.x 上才有作用,这意味着,当你使用 0.10.x 时,即使配置了默认扩展为md
,最后创建的文件,其扩展名仍然是page
。
default-page-type
: Markdown # 默认页面类型front-page
: index # 首页文件no-edit
: Help # 禁止编辑的页面, 逗号分隔no-delete
: index, Front Page, Help # 禁止删除的页面/文件,逗号分隔default-summary
: automatically added commit message. # 默认编辑摘要,为空时,编辑一个条目时,如果不输入编辑摘要,Gitit 就会返回错误,要求必须手动输入。- 授权相关:gitit 支持 github 接入,但我没有使用,也没有研究。
- 安全相关: gitit 默认使用 html 表单认证,而非 HTTP 方式,gitit 默认也启用了防跨站攻击。这里不再详细说明,我直接使用的是默认配置。
其他配置项
其他一些配置项,在我自己使用时,有的做了更改(如文件和页面体积),有的则使用默认的。
table-of-contents
: yes # 是否默认使用 toc 目录,可选项:yes、no。可在页面内配置,见下方页面内配置
repository-type
:Git
# 指定版本控制系统。默认是 Git,可选项有:Git
、Darcs
及Mercurial
。注意
:无论使用何种版本控制系统,运行 Gitit 的宿主 OS 上都必须先安装它。
repository-path
: wikidata # 指定仓库地址,也即 wiki 条目所在的文件夹。- 相对路径。相对于运行
gitit -f my-gitit.conf
时所在的文件夹。 - 如果指定文件夹不存在,gitit 将在启用服务时自动创建。
- 建议不要更改。
- 相对路径。相对于运行
use-recaptcha
,recaptcha-private-key
、recaptcha-public-key
# 是否使用 recaptcha,如要使用,还要配置相关 key。use-feed
: no # 是否启用 feed。feed 还有其他相关配置,比如更新时间等,详情请参阅配置文件内说明。pdf-export
: no # 是否支持 pdf 导出,这需要 pandoc 或其他插件支持,详情请参阅配置文件内说明。max-upload-size
:4096K # 最大文件上传尺寸。max-page-size: 1024K
# 页面最大尺寸。
页面内配置
gitit 支持在编辑页面时来配置当前页面。
可用选项
title
: 页面标题toc
: 是否使用 toc。可选项:yes
、no
。默认为yes
.categories
: 页面所属分类,空格或英文逗号分隔,建议使用英文逗号。format
: 页面格式,比如markdown
,或markdown+lhs
。我只使用markdown
,配置文件里也有指定,因此很少在页面内使用这个配置。
完整示例
---
title: 这是一个页面的标题
toc: yes/no
categories: Miao, Wu, 分类呢
format: markdown+lhs
...
注意,必须严格按照此格式,否则无效。...
是必须的,:
是英文的。
通过 shell 来编辑 wiki
wikidata
是一个仓库目录,只要该文件夹下的文件被 git add
到仓库并执行了 git commit
,gitit 将会把它们当作 wiki 条目加入到系统中。
因此,我们可以通过 shell 下的一系列操作来编辑 wiki。比如:
cd /path/to/your/wikidata
touch new_page.md
echo "hello shajiquan" >> new_page.md
git add new_pge.md
git commit -m "add new_page.md file"
echo "new line" >> old_page.md
git add old_page.md
git commit -m "update old_page.md "
git push origin master
缺憾及解决方案
- 界面较丑:像我这样弄一套 bootstrap 模板;
无用户管理/限制:稍差,但如果是私用或者小范围使用,倒也足够。
- 请参阅
require-authentication
、access-question
、access-question-answers
配置项。 - 创建自己所需要的用户后,可以将项目目录的
gitit-users
文件权限设置为只读。
- 请参阅
编辑器较差:像我这样启用 ace 编辑器即可(markdown 模式);
- 某些更改必须重启才能生效:如果 gitit 配置文件、模板、静态文件有修改,必须重启 gitit,这很好办,用命名或脚本都可以轻松做到。
- 使用
cabal
方式安装最新版本时:- 安装麻烦:安装过程比较慢,巨慢。没办法,只能慢慢来。
- 安装失败:在某些版本的操作系统上可能会安装失败,因为它的依赖和操作系统的不符。
- 我没搞定,正巧我有台 ubuntu 主机支持,于是就安装成功了。个人用的 mac 上也成功了。
- 如果你没有合适的主机,可以考虑用 docker 来安装。
文件结构
.
├── gitit-users
├── gitit.log
├── my-gitit.conf
├── static
│ ├── css
│ │ └── custom.css
│ └── img
│ └── logo.png
├── templates
│ └── footer.st
└── wikidata
├── gitit
│ ├── guide.md
├── index.md
├── sandbox.md
安装
Ubuntu/debian
使用 apt-get
sudo apt-get install gitit
注意,目前 apt-get
安装的 Gitit 应该还是 0.10.x 版本,而官方目前最新版本是 0.11.x。依我个人经验来看,并无太大差别。但 0.11.x 有个我特别喜欢的新功能:自定义文件名后缀。
在 0.10.x 下,即使你在配置文件里设置后缀为 md
,最后 gitit 生成的文件依然是 page
。如果使用 .md 的话,无论是用浏览器查看,还是用 OS 的编辑器打开时,可能效果都更好。
但是,如果要安装 0.11.x,请做好时间上的准备,这个安装过程非常耗时、费力(也许是在下愚笨,如有好方法,还望告知我)。
使用 cabal
sudo apt-get install -y git cabal-install libghc-zlib-dev
cabal update && cabal install gitit
echo "export PATH=~/.cabal/bin:$PATH" >> ~/.bash_profile
source ~/.bash_profile
Mac OS X
brew update && brew install cabal-install
cabal-install install gitit
部署
依配置文件&后台运行
nohup gitit -f my-gitit.conf > logs-gitit.log & echo $! > pid-my-gitit.conf.pid 2>&1 &
自动 Pull/Push
* * * * * /path-to/auto-data.sh > /path-to/logs-auto-data.log 2>&1 &
使用我的版本
我的版本做了如下变动:
- 安装了 Bootstrap 模板(via Changaco/gitit-bootstrap)
- 安装了 Ace Editor (via Getting the Ace editor to work with gitit)
Ace Editor 的编辑模式已设为
markdown
。- 支持代码高亮
- 搜索、替换(cmd+option+f)
- Tab 缩进、恢复(tab、shift+tab)
- …
采用配置文件方式启动
默认使用—— 现在使用默认的md
文件后缀(必须使用 gitit 0.11.1+)page
了,主要是方便在不同系统上部署,等到 apt-get 的源都已经升级为 0.11.x 时再切换回md
。- 支持在我的版本上自定义 CSS/JSS(在
templates/page_more_scripts.st
中,详见下文) - 启用了部分安全相关配置
- 增加了启动、部分、自动备份脚本或帮助
配置 git
如果你已经配置,略过此步。
git config --global user.name Your Name
git config --global user.email Your Email
clone 我的 gitit 项目
git clone https://github.com/shajiquan/gitit-bigger ~/workspace/gitit
cd ~/workspace/gitit
git branch --set-upstream-to=origin/master master
cp sample.gitit.conf my-gitit.conf
更改基本配置
根据你的需要,修改 my-gitit.conf
配置文件,如:
port
: 7500wiki-title
: 危机百科
clone 你的数据
cd ~/workspace/gitit
git clone your-wikidata.git ./wikidata
git branch --set-upstream-to=origin/master master
自动备份
- 运行
./run/gen_crontab_cmd.py
- 得到类似
* * * * * /auto-data.sh > /log-auto-data.log 2>&1 &
命令。 - 运行
crontab -e
并将刚才得到的命令粘贴到底部,关闭文件即可。
启用 gitit 服务
cd ~/workspace/gitit
./run/run.sh start
此时,就可以访问 wiki 了:http://ip|domain:7500
这将使用 nohup
的方式使用服务在后台运行,当然了,你也可以使用 supervisord
之类来管理。
更改扩展名
背景:
- 正如上文所说,gitit 0.11.x 支持配置文件扩展名,0.10.x 不支持。即使我们配置
default-extension
为md
,gitit 仍然会将新建的文件的扩展名设为page
。 - 而目前
apt-get
安装源中的 gitit 都是 0.10.x,如果你要使用 0.11.x,必须使用cabal
来安装,而使用cabal
安装时,却可能因为各种原因安装失败。
我们可能会因为某些原因需要将自己的 wiki 条目文件的扩展名进行批量更改,比如从 md
改为 page
,或者从 page
改为 md
,或者从 txt
、markdown
改为 md
。
我写了一个脚本来做这个事情:./run/batch_renamer_by_ext.py
,基本用法如下:
./batch_renamer_by_ext.py --d /path/to/wikidata --f txt --t md --add False --push False --commit False
--d
: wiki 条目所在目录,必须使用绝对路径,如/home/shajiquan/gitit/wikidata
。如果不传入,脚本会将脚本所在目录当作目标目录。--f
: 原始后缀名,默认为page
。--t
: 目标后缀名,默认md
。--add
、--commit
、--push
:是否在更改后缀名之后进行 git 的相关操作,默认为True
。指定非True
值时,脚本将不会执行相关的 git 操作。注意
: 如果你使用脚本进行批量处理了,但没有将新文件git add
到仓库里,或者没有执行git commit
,那么你的 wiki 中将不会有这些条目。
限制用户
- 请参阅
require-authentication
、access-question
、access-question-answers
配置项。 - 创建自己所需要的用户后,可以将项目目录的
gitit-users
文件权限设置为只读。
Docker 版
要点如下:
- 使用 debian 系统;
- 使用 supervisord 进程管理;
- 支持挂载已存在的 gitit 项目文件夹(建议采用这种方案来启动容器);
关于批量修改文件名后缀、自动备份数据(push 到远程仓库)请参见上文。
如果不挂载已有 gitit 项目,可能带来的问题:
git
相关配置如 user、email 需要自己进入到容器中单独配置。git
推送相关,也需要单独处理(ssh keys、 git remote 等)。
虽然我们可以尝试把宿主环境的相关配置复制到容器中,或者手动进入容器更改,但仍然麻烦,不如挂载宿主环境上的 gitit 项目更省事。
不挂载已有 gitit
docker run -d --name gitit -p 7500:7500 shajiquan/gitit
挂载已有 gitit
假设你的 gitit 项目在 ~/workspace/gitit
下,将此目录挂载到 docker 容器里:
docker run -d --name gitit -p 7500:7500 -v ~/workspace/gitit:/data/gitit shajiquan/gitit
重启 docker 容器中的 gitit 服务
如果 gitit 配置文件、模板、静态文件有修改,必须重启 gitit。假设你的容器名称是 gitit
,使用容器内的 supervisord
来重启 gitit 服务:
docker exec -d gitit supervisorctl restart gitit
或者
docker ps -a | grep 'gitit' | awk '{print $1}' |xargs -i docker exec -itd {} supervisorctl restart gitit
进入到容器的 shell 中
假设你的容器名称是 gitit
:
docker exec -it gitit bash
挂载卷
本镜像支持挂载一个已存在的 gitit 文件夹到容器中。我建议使用已存在的 gitit 项目。
容器中的 Gitit 工作目录是: /data/gitit
。容器在启用时将会检测如下文件,如果他们不存在,将会复制一份默认版。
/data/gitit/my-gitit.conf
/data/gitit/supervisord.conf
Gitit 服务启用时将自动创建如下目录(如果它们不存在) :
/data/gitit/static/
:必须的静态文件;/data/gitit/templates/
模板;/data/gitit/wikidata/
Wiki 页面所在目录,一个 git repo;
自定义 JS/CSS
templates/page_more_scripts.st
这个文件已被引入到 templates/page.st
(模板主文件)中,但这个 more 文件,并没有被加入到 git 版本控制中。
因此,你可以在 page_more_scripts.st
中定制 CSS/JS。在 Gitit 的系统里,这个文件将被当作 HTML
来处理。我的内容如下:
<link rel="stylesheet" href="/js/highlight/styles/monokai_sublime.css">
<script src="/js/highlight/highlight.pack.js"></script>
<script>
// more js scripts here
// jquery shoud be escaped. or you can just use jQuery(document)
\$("#content").ready(function(){
\$("#content a[href^='http://']").attr("target","_blank");
\$('pre').each(function(i, block) {
hljs.highlightBlock(block);
});
});
</script>
Links
- Github:https://github.com/shajiquan/gitit-bigger
- DockreHub:https://hub.docker.com/r/shajiquan/gitit
- Demo: http://wiki.shajiquan.com/gitit-bigger (Read Only)
- gitit official site: http://gitit.net
- gitit official github: https://github.com/jgm/gitit
- 在Archlinux上部署gitit Wiki: http://www.360doc.com/content/12/0518/21/21412_211977928.shtml
- Gitit - git based wiki: http://walkingice.blogspot.hk/2011/11/gitit-git-based-wiki.html
- Hyzual/docker-gitit: https://github.com/Hyzual/docker-gitit