點開spring-boot
的官方倉庫,README
卻不是咱們熟知的markdown
格式,而是adoc
。git
adoc
的官網也明確列出了它的優點,能夠裝換爲HTML5
、DocBook
及更多格式。github
測試了一下,裝換爲網頁後,效果還不錯。spring
官網有好多種安裝方法,APT
、Homebrew
、Chocolatey
。shell
挺喜歡Mac
下的Homebrew
的,十分方便,可是看了好多篇博客,都是用的Gem
安裝,內心想着,第一次接觸這個,仍是在借鑑前人的好,萬一碰到問題也能夠查閱資料,遂選擇了Gem
。瀏覽器
Gem
是Ruby
的包管理器,我這裏直接能夠用,多是系統自帶的?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
的權限,上sudo
。markdown
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
一路順利,安裝成功。
撰寫基本沒什麼問題,就是原來markdown
中這麼寫,而後切換到adoc
中改了一下格式。
官網有語法參考,和Bootstrap
差很少,文檔寫得特別好。
會有示例的demo
,點擊右上角的view result
,下面會彈出來這段文字最終顯示的效果。
HTML
生成HTML
一點毛病都沒有,很簡單。
asciidoctor README.adoc
直接在後面寫上文檔名便可,便可生成同名的HTML
文檔。
用瀏覽器打開,效果還不錯。
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
也生成出來了,就是有問題。
你們應該也看出問題了,少字!
後來發現是字體的原理,字體沒有這個字,就顯示不出來。
安裝字體
sudo asciidoctor-pdf-cjk-kai_gen_gothic-install
這裏應該是網絡的問題,我下了好屢次,一直是網絡超時。
最終放棄,去官方倉庫手動下載字體。
下字體,也不知道哪一個有用哪一個沒用,乾脆就把一共20
個字體都下下來了。
gem environment
找到INSTALLATION DIRECTORY
一項,這就是Gem
軟件包安裝目錄。
/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts
把下載的字體移動到該目錄中。
asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN README.adoc
再次執行命令,執行時指定生成PDF
的主題。
大功告成!
參考前人的經驗,總好過本身的獨斷獨行。