前言
部門目前搭建了自己的gitlab服務(wù)器, 用于代碼管理, 但是其實gitlab的功能不止于此, 這不, 近期研究了下關(guān)于部門技術(shù)文檔管理的方法, 就發(fā)現(xiàn)了gitlab的wiki功能, 為我們的文檔管理提供了完美的解決方案, 下面就對此進行一些說明, 并記錄一下自己的踩坑與填坑經(jīng)歷.
關(guān)于wiki
網(wǎng)上有一個公式, git + markdown = wiki, 雖然不是很準確(因為wiki不只是支持markdown), 但卻是很直觀的解釋了什么是wiki, wiki就是利用git來進行文檔管理的一種方法, 就好像我們用git管理代碼一樣.
gitlab上wiki的使用
wiki的使用很簡單, 只要我們登陸到gitlab, 進入到wiki界面一看便知, 直接可以創(chuàng)建頁面, 側(cè)邊欄可以查看已經(jīng)創(chuàng)建的文檔, 進入文檔后可以瀏覽, 也可以進行編輯, 編輯完可以直接提交, 當然也可以寫提交日志, 非常簡單, 這里就不貼圖了.
上面說的是在線操作, 但其實它和代碼管理一樣, 也可以克隆到本地進行修改, 然后再提交推送. 我們需要先進入wiki頁面(在右側(cè)邊欄有一個'更多頁面'按鈕), 進入后就可以找到克隆地址了, 使用你熟悉的方法克隆到本地, 然后就可以在本地進行編輯了.
gitlab的markdown語法
我也不確定gitlab的markdown語法是否標準, 就目前使用的情況來看可能會與一些其他的markdown編輯器在語法上有些不同, 比如不支持toc(當然這是擴展命令), 還有我這篇文章中提到的錨點等, 但我覺得大部分語法都是通用的, 大家在使用過程中如果發(fā)現(xiàn)不兼容的地方可以記錄下, 尤其是習(xí)慣在本地操作的, 可能需要和一些編輯器進行兼容, 這樣也方便我們導(dǎo)出為其他格式的文檔.
關(guān)于本地操作使用的工具
官方建議的是使用gollum, 但其實我一直也沒試用過這個工具, 看網(wǎng)上說雖然它的安裝步驟很簡單, 但它需要一些環(huán)境依賴, 真正安裝起來其實挺麻煩的, 而且我看介紹它也是在瀏覽器中進行編輯, 我不習(xí)慣, 所以直接沒有嘗試.
這里我想給大家推薦一款工具 -- Typora.
這款軟件在markdown編輯軟件中應(yīng)該還是挺出名的(關(guān)于markdown的編輯軟件, 我這篇文章有說明, 感興趣的可以移步),.
- Typora是一款實時渲染的工具, 你在使用markdown寫作時, 它可以實時轉(zhuǎn)換markdown格式, 方便你查看排版;
- Typora支持toc命令, 可以一鍵生成目錄, 而且親測它生成的目錄在gitlab的wiki中是兼容的;
- Typora的圖片沒有居中格式, wiki中的圖片可以通過<div align=center>圖片居中</div>來實現(xiàn)圖片居中顯示, 而這種方式在Typora中不支持, 而且連圖片也不顯示, 為了兼容, 建議在wiki中使用<div align=center>圖片居中</div>進行圖片居中時, 在<div align=center>后多加一個空行, 這樣的話在wiki仍然可以居中, 而且可以保證在typora中圖片也能顯示, 如果是文字居中的話, 是可以使用<center></center>來實現(xiàn)的;
- Typora可以在側(cè)邊欄顯示目錄結(jié)構(gòu)圖, 方便本地文檔的管理;
- Typora支持的導(dǎo)出格式非常多, 感覺完全可以替代gitbook了都.
- 如果將Typora的圖片插入設(shè)置為相對路徑優(yōu)先, 并且自動復(fù)制到指定目錄下的話, 可以實現(xiàn)和gitlab的無縫連接, 在本地編輯好, 連帶圖片一起推送, 在gitlab可以完美顯示圖片.
最后
由于我也是剛開始使用wiki和Typora, 所以有很多地方還不熟悉, 如果有說錯的地方還請大家留言指正,.
如果自己的文章對你多少有點幫助的話, 還請您動動手指給點個贊哦.
