前言
此文件為Gitit初始化生成的文件。恰巧和
Gitit在Github上的說明一模一樣。
Gitit
Gitit是一個用
Haskell語言撰寫而成的
Wiki引擎。使用
Happstack當Web serivce並且使用
pandoc處理標記語言的轉換。wiki頁面和上傳的檔案可以選擇儲存在任何分散式版本控制工具中(例如
git,
darcs或
mercurial)，而且可以使用VCS(Version Control Systems)的指令或透過wiki提供的Web界面來操作。預設情況下, 預設的標記語言是用
markdown的擴充版配合
pandoc的轉檔軟體，但也包含 reStructuredText、LaTeX、HTML、DocBook或Emacs Org-mode的標記方式。wiki頁面可以轉成許多不同的格式，包含LaTeX, RTF, OpenOffice ODT以及MediaWiki(一般wiki百科的那種)標記方式。設定Gitit的config可以顯示TeX math (用
texmath)和標示程式碼(source code)(用
highlighting-kate)。
其他功能還包括
- 外掛程式(plugins): dynamically loaded page transformations written in Haskell (see “Network.Gitit.Interface”)
- 分類(categories)
- TeX math
- 程式碼語法標示和程式碼片段 (using highlighting-kate)
- 快取(caching)
- 支援Atom訂閱 (包含網站和每個頁面)
- a library, “Network.Gitit”, that makes it simple to include a gitit wiki in any happstack application
你可以看這些功能的Demo在。
Getting 起步走(Getting started)
編譯和安裝gitit(Compiling and installing gitit)
你需要
GHC編譯器和
cabal-install安裝工具。GHC的
載點。要注意，下載的版本必須是release 0.5、GHC 6.10或更高版本。
cabal-install安裝工具必須在like unix作業系統上運作。以下是快速安裝說明。
一旦你取得了cabal-install安裝工具，安裝gitit就是最平凡小事(trivial)了：
cabal update
cabal install gitit
要安裝最新版的gitit，只要輸入這些命令。要安裝某一個版本的gitit，要從資源庫(repository)簽出(checked out)來，修改gitit的資料夾，然後再輸入:
cabal install
cabal安裝工具會自動安裝所有需要的Haskell的程式庫(libraries)。順利的話，這個過程最後會自己結束，gitit的最新版本將被安裝在你的電腦裡。cabal的資料夾。你可以用這個指令檢查:
gitit --version
如果不順利，檢查gitit是否在你local cabal-install的可執行目錄(通常是
~/.cabal/bin)。並確保
~/.cabal/bin設定成系統路徑。
設定支援語法標示(Optional syntax highlighting support)
If pandoc was compiled with optional syntax highlighting support, this will be available in gitit too. This feature is recommended if you plan to display source code on your wiki.
如果pandoc使用語法標示選項來編譯， 同樣也可以在gitit上使用。 如果你計畫在wiki上顯示原始碼，推薦使用此功能。
Highlighting support requires the
pcre library, so make sure that is installed before continuing.
語法標示支援需要
pcre函數庫，請在繼續之前確認已經安裝。
To install gitit with highlighting support, first ensure that pandoc is compiled with highlighting support, then install gitit as above:
在gitit安裝語法標示前，先確認pandoc是被編譯成語法標示，再依據下列指令安裝：
cabal install pandoc -fhighlighting --reinstall
cabal install gitit
執行Gitit(Running gitit)
To run gitit, you’ll need
git in your system path. (Or
darcs or
hg, if you’re using darcs or mercurial to store the wiki data.)
在執行gitit之前，你需要確認
git在作業系統路徑下。 (如果你使用
darcs或
mercurial來儲存wiki的資料，確認
darcs與
hg在作業系統路徑下。)
Gitit assumes that the page files (stored in the git repository) are encoded as UTF-8. Even page names may be UTF-8 if the file system supports this. So you should make sure that you are using a UTF-8 locale when running gitit. (To check this, type
locale.)
Gitit預設頁面檔案(儲存在git repository)是以UTF-8儲存，如果檔案系統支援以UTF-8儲存， 甚至頁面名稱也是以此格式儲存。所以確認你的gitit是使用UTF-8的語言環境。(請檢查, type
locale.)
Switch to the directory where you want to run gitit. This should be a directory where you have write access, since three directories,
static,
templates, and
wikidata, and two files,
gitit-users and
gitit.log, will be created here. To start gitit, just type:
可以更改gitit執行目錄到你想要的位置，但必須確認你擁有寫入的權限。 開始使用gitit只要輸入以下命令， 就會建立包含
static,
templates,
wikidata三個目錄，和兩個檔案
gitit-users,
gitit.log
gitit
If all goes well, gitit will do the following:
如果一切順利，這個指令會執行下列動作：
- Create a git repository,
wikidata, and add a default front page.
- Create a
static directory containing files to be treated as static files by gitit.
- Create a
templates directory containing HStringTemplate templates for wiki pages.
- Start a web server on port 5001.
- 建立一個git的儲存庫
wikidata, 和增加一個預設的頁面.
- 建立一個
static目錄，包含一些初始化檔案.
- 建立一個
templates目錄，包含 HStringTemplate templates給各個頁面.
- 在連接埠
5001啟動一個 Web Server.
Check that it worked: open a web browser and go to
http://localhost:5001.
開啟瀏覽器輸入確認是否正常運作.
You can control the port that gitit runs on using the
-p option:
gitit -p 4000 will start gitit on port 4000. Additional runtime options are described by
gitit -h.
你可以使用
-p 選項，例如:
gitit -p 4000 將更改連接埠至
4000。 最後你可以在執行時使用
gitit -h取得說明。
使用Gitit(Using gitit)
For instructions on editing pages and creating links, see the “Help” page.
有關編輯頁面和創建連結的說明，請參閱“幫助”頁面。
Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages,
[Front Page]() creates an internal wikilink to the page
Front Page. In reStructuredText pages,
`Front Page <>`_ has the same effect.
Gitit 會將空的連結當作是 wikilinks， 進而建立一個新頁面。
[Front Page]() 會建立一個內部的 wikilink 到
Front Page. 在 reStructuredText 頁面使用
`Front Page <>`_ 有相同效果。
If you want to link to a directory listing for a subdirectory, use a trailing slash:
[foo/bar/]() creates a link to the directory for
foo/bar.
如果你想要一個連結清單到根目錄， 可以使用下列語法，來建一個連結到
foo/bar目錄：
[foo/bar/]()
頁面後設資料(Page metadata)
在頁面開頭可以加入後設資料
非必要。範例如下：
---
format: latex+lhs
categories: haskell math
toc: no
title: Haskell and
Category Theory
...
\section{Why Category Theory?}
後設資料由
key-value列表組成，每一行為單獨的
key-value。 如果需要
key可以用空白隔開連接多個
key'。(這裡有一個插圖標頭的範例)後設資料第一行必須以—
為開頭，並且最後必須以…
或一個以上的空白行
為結束。(後設資料是有效的非標記式語言
[(YAML)](http://zh.wikipedia.org/wiki/YAML)文件, 雖然不是所有非標記式語言`文件在後設資料都是有效的)
後設資料目前支援的key如下:
format- 指定顯示此頁以何種語法解讀
允許的值是 markdown、rst、latex、html、markdown+lhs、
rst+lhs、latex+lhs。(忽略大小寫，所以你也可以寫成LaTeX、HTML…等)
設定+lhs意思是，如果另一個語法出問題，該文章就當作Haskell來顯示。
categories- 頁面標籤，可以在左列的分類索引(categories)中新增徢徑。
toc- 變更configuration檔設定的table-of-contents
- 簡單的說，就是設定每一頁的大綱是否顯示
- 值可以設定成
yes、no或true、false (忽略大小寫)。
title- 替代原本的文件名稱當文章標題。(預設的文章標題，就是檔案名稱)
標記程式碼(Highlighted source code)
如果編譯gitit針對一個已經有支援標示程式碼的Pandoc版本 (see above)，你可以
界定程式碼區塊(
delimited code blocks)來標示程式碼語法:
~~~ {.haskell .numberLines}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
~~~
用下面的指令可以看到你編譯的Pandoc支持了什麼的語言的標示
pandoc -v
設定和個人化Gitit(Configuring and customizing gitit)
設定選項(Configuration options)
使用這個參數
-f [filename] 指定config設定檔:
gitit -f my.conf
如果不使用這個選項，gitit會使用預設的config設定。為了取得 你可以輸入下面的指令取得目前gitit的預設config的副本:
gitit --print-default-config > my.conf
預設的config檔是有經過註解的
文件。
static資料夾(The static directory)
若收到一個request訊息，gitit總是會先找
static資料夾裡的資料(或任何在
static-dir的檔案(configuration file))如果找到檔案對應到即將要顯示的資料，就會馬上送出。如果在
static找不到的檔案, gitit接下來會依據
static子目錄(
$CABALDIR/share/gitit-x.y.z/data)裡的gitit資料檔。這是儲存預設css、javascripts和圖檔的地方。如果文件沒有找到，gitit會將它視為wiki頁面或wiki的執行指令。
So, you can throw anything you want to be served statically (for example, a
robots.txt file or
favicon.ico) in the
static directory. You can override any of gitit’s default css, javascript, or image files by putting a file with the same relative path in
static. Note that gitit has a default
robots.txt file that excludes all URLs beginning with
/_.
Note: if you set
static-dir to be a subdirectory of
repository-path, and then add the files in the static directory to your repository, you can ensure that others who clone your wiki repository get these files as well. It will not be possible to modify these files using the web interface, but they will be modifiable via git.
使用git以外的版本控制系統(Using a VCS other than git)
By default, gitit will store wiki pages in a git repository in the
wikidata directory. If you’d prefer to use darcs instead of git, you need to add the following field to the configuration file:
repository-type: Darcs
If you’d prefer to use mercurial, add:
repository-type: Mercurial
This program may be called “darcsit” instead of “gitit” when a darcs backend is used.
Note: we recommend that you use gitit/darcsit with darcs version 2.3.0 or greater. If you must use an older version of darcs, then you need to compile the filestore library without the (default) maxcount flag, before (re)installing gitit:
cabal install --reinstall filestore -f-maxcount
cabal install --reinstall gitit
Otherwise you will get an error when you attempt to access your repository.
變更佈景主題(Changing the theme)
改變wiki頁面的排版，只要修改在
static/css的
custom.css。
改變列印頁面的排版，取得一份gitit的預設print.css到
static/css，並且修改它。
想要換掉logo圖的話，可以找一張.png檔，替換掉
static/img/logo.png即可。 預設大小為138×155 pixels。
想要修改註腳(footer)的話，修改
templates/footer.st。
如果想要修改更多的話，可以重寫預設模版(template)，在
$CABALDIR/share/gitit-x.y.z/data/templates可以找到，再放到
templates資料夾中，就會以此模版為顯示模版。其中
page.st是主幹模版(master template)；由它來引用其它的模版。 模版內使用的變數，用
$
Interpolated variables are surrounded by
$s, so
literal $ must be backslash-escaped.
增加數學支援(Adding support for math)
To write math on a markdown-formatted wiki page, just enclose it in dollar signs, as in LaTeX:
Here is a formula: $\frac{1}{\sqrt{c^2}}$
You can write display math by enclosing it in double dollar signs:
$$\frac{1}{\sqrt{c^2}}$$
Gitit can display TeX math in three different ways, depending on the setting of
math in the configuration file:
mathml (default): Math will be converted to MathML using texmath. This method works with IE+mathplayer, Firefox, and Opera, but not Safari.jsMath: Math will be rendered using the jsMath javascript. If you want to use this method, download jsMath and jsMath Image Fonts from the jsMath download page. You’ll have two .zip archives. Unzip them both in the static/js directory (a new subdirectory, jsMath, will be created). This works with all browsers, but is slower and not as nice looking as MathML.raw: Math will be rendered as raw LaTeX codes.
限制存取(Restricting access)
If you want to limit account creation on your wiki, the easiest way to do this is to provide an
access-question in your configuration file. (See the commented default configuration file.) Nobody will be able to create an account without knowing the answer to the access question.
如果你想要限制建立帳號的權限，最簡單的方式是提供
access-question在你的設定檔案。 (請參閱預設的設定檔案解說)
在不知道
access-question的答案下，就無法建立帳號。
Another approach is to use HTTP authentication. (See the config file comments on
authentication-method.)
另一種方法是使用HTTP認證。 （請參閱配置文件中的註釋上
authentication-method）
外掛程式(Plugins)
Plugins are small Haskell programs that transform a wiki page after it has been converted from Markdown or RST. See the example plugins in the
plugins directory. To enable a plugin, include the path to the plugin (or its module name) in the
plugins field of the configuration file. (If the plugin name starts with
Network.Gitit.Plugin., gitit will assume that the plugin is an installed module and will not look for a source file.)
Plugin support is enabled by default. However, plugin support makes the gitit executable considerably larger and more memory-hungry. If you don’t need plugins, you may want to compile gitit without plugin support. To do this, unset the
plugins Cabal flag:
cabal install --reinstall gitit -f-plugins
Note also that if you compile gitit for executable profiling, attempts to load plugins will result in “internal error: PAP object entered!”
透過Git存取wiki (Accessing the wiki through git)
All the pages and uploaded files are stored in a git repository. By default, this lives in the
wikidata directory (though this can be changed through configuration options). So you can interact with the wiki using git command line tools:
所有頁面和上傳的檔案被儲存在 git repository. 預設放在
wikidata目錄底下 (當然這可以透過設定檔案更改). 所以你可以使用 git 命令工具操作 wiki:
git clone ssh://my.server.edu/path/of/wiki/wikidata
cd wikidata
vim Front\ Page.page # edit the page
git commit -m "Added message about wiki etiquette" Front\ Page.page
git push
If you now look at the Front Page on the wiki, you should see your changes reflected there. Note that the pages all have the extension
.page.
現在回到Front Page, 可以看到剛剛所做的更改. 每個頁面都有對應的
.page頁面。
If you are using the darcs or mercurial backend, the commands will be slightly different. See the documentation for your VCS for details.
如果你使用
darcs 或
mercurial 為後端， 命令會有些不同。 請參考相關的 VCS 詳細說明.
Caching
By default, gitit does not cache content. If your wiki receives a lot of traffic or contains pages that are slow to render, you may want to activate caching. To do this, set the configuration option
use-cache to
yes. By default, rendered pages, highlighted source files, and exported PDFs will be cached in the
cache directory. (Another directory can be specified by setting the
cache-dir configuration option.)
Cached pages are updated when pages are modified using the web interface. They are not updated when pages are modified directly through git or darcs. However, the cache can be refreshed manually by pressing Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to
/_expire/path/to/page, where
path/to/page is the name of the page to be expired.
Users who frequently update pages using git or darcs may wish to add a hook to the repository that makes the appropriate HTTP request to expire pages when they are updated. To facilitate such hooks, the gitit cabal package includes an executable
expireGititCache. Assuming you are running gitit at port 5001 on localhost, and the environment variable
CHANGED_FILES contains a list of the files that have changed, you can expire their cached versions using
expireGititCache http://localhost:5001 $CHANGED_FILES
Or you can specify the files directly:
expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c
This program will return a success status (0) if the page has been successfully expired (or if it was never cached in the first place), and a failure status (> 0) otherwise.
The cache is persistent through restarts of gitit. To expire all cached pages, simply remove the
cache directory.
Idle
By default, GHC’s runtime will repeatedly attempt to collect garbage when an executable like Gitit is idle. This means that gitit will, after the first page request, never use 0% CPU time and sleep, but will use ~1%. This can be bad for battery life, among other things.
To fix this, one can disable the idle-time GC with the runtime flag
-I0:
gitit -f my.conf +RTS -I0 -RTS
在Gitit使用Apache(Using gitit with apache)
Most users who run a public-facing gitit will want gitit to appear at a nice URL like
http://wiki.mysite.com or
http://mysite.com/wiki rather than
http://mysite.com:5001. This can be achieved using apache’s
mod_proxy.
Proxying to http://wiki.mysite.com
Set up your DNS so that
http://wiki.mysite.com maps to your server’s IP address. Make sure that the
mod_proxy module is loaded, and set up a virtual host with the following configuration:
<VirtualHost *>
ServerName wiki.mysite.com
DocumentRoot /var/www/
RewriteEngine On
ProxyPreserveHost On
ProxyRequests Off
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPassReverse / http://127.0.0.1:5001
RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
ErrorLog /var/log/apache2/error.log
LogLevel warn
CustomLog /var/log/apache2/access.log combined
ServerSignature On
</VirtualHost>
Reload your apache configuration and you should be all set.
Using nginx to achieve the same
Drop a file called
wiki.example.com.conf into
/etc/nginx/conf.d (or where ever your distribution puts it).
server {
listen 80;
server_name wiki.example.com
location / {
proxy_pass http://127.0.0.1:5001/;
proxy_set_header X-Real-IP $remote_addr;
proxy_redirect off;
}
access_log /var/log/nginx/wiki.example.com.log main;
}
Reload your nginx config and you should be all set.
Proxying to http://mysite.com/wiki
Make sure the
mod_proxy,
mod_headers,
mod_proxy_http, and
mod_proxy_html modules are loaded.
mod_proxy_html is an external module, which can be obtained
here (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that occur in web pages. Here we will use it to rewrite gitit’s links so that they all begin with
/wiki/.
First, tell gitit not to compress pages, since
mod_proxy_html needs uncompressed pages to parse. You can do this by setting the gitit configuration option
compress-responses: no
Second, modify the link in the
reset-password-message in the configuration file: instead of
http://$hostname$:$port$$resetlink$
set it to
http://$hostname$/wiki$resetlink$
Restart gitit.
Now add the following lines to the apache configuration file for the
mysite.com server:
# These commands will proxy /wiki/ to port 5001
ProxyRequests Off
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /wiki/ http://127.0.0.1:5001/
<Location /wiki/>
SetOutputFilter proxy-html
ProxyPassReverse /
ProxyHTMLURLMap / /wiki/
RequestHeader unset Accept-Encoding
</Location>
Reload your apache configuration and you should be set.
For further information on the use of
mod_proxy_http to rewrite URLs, see the
mod_proxy_html guide.
Using gitit as a library
By importing the module
Network.Gitit, you can include a gitit wiki (or several of them) in another happstack application. There are some simple examples in the haddock documentation for
Network.Gitit.
回報bug(Reporting bugs)
Bugs may be reported (and feature requests filed) at
http://code.google.com/p/gitit/issues/list.
There is a mailing list for users and developers at
http://groups.google.com/group/gitit-discuss.
致謝(Acknowledgements)
A number of people have contributed patches:
- Gwern Branwen helped to optimize gitit and wrote the InterwikiPlugin. He also helped with the Feed module.
- Simon Michael contributed the patch adding RST support.
- Henry Laxen added support for password resets and helped with the apache proxy instructions.
- Anton van Straaten made the process of page generation more modular by adding Gitit.ContentTransformer.
- Robin Green helped improve the plugin API and interface, and fixed a security problem with the reset password code.
- Thomas Hartman helped improve the index page, making directory browsing persistent, and fixed a bug in template recompilation.
- Justin Bogner improved the appearance of the preview button.
- Kohei Ozaki contributed the ImgTexPlugin.
- Michael Terepeta improved validation of change descriptions.
- mightybyte suggested making gitit available as a library, and contributed a patch to ifLoggedIn that was needed to make gitit usable with a custom authentication scheme.
I am especially grateful to the darcs team for using darcsit for their public-facing wiki. This has helped immensely in identifying issues and improving performance.
Gitit’s default visual layout is shamelessly borrowed from Wikipedia. The stylesheets are influenced by Wikipedia’s stylesheets and by the bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
img/icons come from bluetrip as well.
