ADOC Guide

引言

點開spring-boot的官方倉庫,README卻不是咱們熟知的markdown格式,而是adocgit

clipboard.png

clipboard.png

adoc的官網也明確列出了它的優點,能夠裝換爲HTML5DocBook及更多格式。github

測試了一下,裝換爲網頁後,效果還不錯。spring

clipboard.png

使用

安裝

官網有好多種安裝方法,APTHomebrewChocolateyshell

挺喜歡Mac下的Homebrew的,十分方便,可是看了好多篇博客,都是用的Gem安裝,內心想着,第一次接觸這個,仍是在借鑑前人的好,萬一碰到問題也能夠查閱資料,遂選擇了Gem瀏覽器

GemRuby的包管理器,我這裏直接能夠用,多是系統自帶的?ruby

gem install asciidoctor

話很少說,進入shell就是敲。bash

Fetching: asciidoctor-1.5.8.gem (100%)
ERROR:  While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.3.0 directory.

錯了,你沒有寫入/Library/Ruby/Gems/2.3.0的權限,上sudomarkdown

sudo gem install asciidoctor
Password:
Fetching: asciidoctor-1.5.8.gem (100%)
ERROR:  While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /usr/bin directory.

仍是沒有權限,你沒有/usr/bin的權限,查閱了一下,在MacOS中,/usr/bin是受系統保護的目錄,即使是root也無權操做。網絡

sudo gem install -n /usr/local/bin asciidoctor

解決方案,換一個目錄:猜測多是建立軟連接的時候出現錯誤,/usr/bin沒有權限,那就把軟連接放在/usr/local/bin裏,同樣能夠用。spring-boot

clipboard.png

一路順利,安裝成功。

語法

撰寫基本沒什麼問題,就是原來markdown中這麼寫,而後切換到adoc中改了一下格式。

官網有語法參考,和Bootstrap差很少,文檔寫得特別好。

clipboard.png

會有示例的demo,點擊右上角的view result,下面會彈出來這段文字最終顯示的效果。

生成HTML

生成HTML一點毛病都沒有,很簡單。

asciidoctor README.adoc

直接在後面寫上文檔名便可,便可生成同名的HTML文檔。

clipboard.png

用瀏覽器打開,效果還不錯。

clipboard.png

生成PDF

生成PDF就沒有那麼順利了。

安裝PDF生成工具:

sudo gem install -n /usr/local/bin --pre asciidoctor-pdf
asciidoctor-pdf README.adoc

網上好多的解決方案雖然能解決,可是容易讓人看懵圈,其實很簡單的東西,就一直打這個命令,它提示什麼,就安裝什麼。

asciidoctor: WARNING: gem 'concurrent-ruby' is not installed. This gem is recommended when registering custom converters.

提示少concurrent-ruby,裝。

sudo gem install -n /usr/local/bin concurrent-ruby

再執行,不報錯了,PDF也生成出來了,就是有問題。

clipboard.png

clipboard.png

你們應該也看出問題了,少字!

後來發現是字體的原理,字體沒有這個字,就顯示不出來。

安裝字體

sudo asciidoctor-pdf-cjk-kai_gen_gothic-install

這裏應該是網絡的問題,我下了好屢次,一直是網絡超時。

clipboard.png

最終放棄,去官方倉庫手動下載字體

下字體,也不知道哪一個有用哪一個沒用,乾脆就把一共20個字體都下下來了。

clipboard.png

gem environment

clipboard.png

找到INSTALLATION DIRECTORY一項,這就是Gem軟件包安裝目錄。

/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts

把下載的字體移動到該目錄中。

clipboard.png

asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN README.adoc

再次執行命令,執行時指定生成PDF的主題。

clipboard.png

clipboard.png

大功告成!

總結

參考前人的經驗,總好過本身的獨斷獨行。

相關文章
相關標籤/搜索