一起唱DoReMi: 5月 2020

2020年5月28日星期四

靜態網頁部落格工具 Ruby + Jekyll 安裝教學

一、安裝Ruby

作業系統為Ubuntu 20，指令如下：

sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev

設定用戶的環境變數，應避免用root安裝Ruby Gems。

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

二、安裝Jekyll

Ruby中使用Gem作為套件管理的工具，就像是python和pip的關係。安裝套件的方式 gem install [packageName]：

gem install jekyll bundler

三、建立新專案

新增一個 myblog 的專案

jekyll new myblog

在目錄下應該會發現新的資料夾 /myblog，大致的內容可以參考一下。

├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
├── _posts
│   └── 2020-05-27-welcome-to-jekyll.markdown
└── _site
    ├── 404.html
    ├── about
    ├── assets
    ├── feed.xml
    ├── index.html
    └── jekyll

四、開啟服務

進入目錄後，啟動伺服器，預設主機名稱localhost、埠號4000，可以根據需求設定：

cd myblog
bundle exec jekyll serve

// or you can ...
bundle exec jekyll serve --host=[ip address] --port=[port number]

瀏覽器開啟 http://localhost:4000 ，就可以看到預設的首頁，安裝就告一段落，可以開始進行開發。

參考資料：https://jekyllrb.com/docs/

2020年5月26日星期二

Asciidoctor + VS Code安裝外掛套件快速開發、預覽功能

一、安裝套件

方法一
(1) 按快捷鍵 [ctrl] + [P]
(2) 輸入下面的指令:

ext install joaompinto.asciidoctor-vscode

(3) 按 [Enter] 送出

方法二
(1) [View] → [Extensions]

(2) 搜尋「AsciiDoc joaompinto」，找到後按綠色按鈕 Install

二、使用方式

打開AsciiDoc的檔案(.adoc, .ad, .asc, .asciidoc)，按下快捷鍵 [ctrl]+[shift]+[v]

三、輸出HTML

快捷鍵 [ctrl]+[alt]+[s]，自動在同一個目錄下產生相同檔名的 html 檔案。

參考資料：https://github.com/asciidoctor/asciidoctor-vscode

2020年5月21日星期四

Asciidoctor 是使用純文字編輯的文檔格式，與 Markdown 用途相近(用法比較)，利用特定的標記可以呈現為HTML、PDF等其他格式，可以根據排版的需求搭配css或模板進行輸出。上一篇「ubuntu18 + python2 文件編輯 AsciiDoc 安裝說明」提到的 AsciDoc 的進化版，AsciDoc 已經停止更新，目前 Asciidoctor 更活耀，常用在電子書或Git專案文件的撰寫。[使用手冊]

安裝

安裝 Asciidoctor(作業系統 Ubuntu 18)

sudo apt-get install -y asciidoctor

完成後可以確認安裝版本

asciidoctor --version
asciidoctor -V

簡易範例

1. 建立檔案
新增一個檔案 sample.adoc，內容：

.Sample document
====
Here's a sample AsciiDoc document:

[listing]
....
= Title of Document
Doc Writer
:toc:

This guide provides...
....

The document header is useful, but not required.
====

2. 輸出 html

asciidoctor sample.adoc

在同一個目錄下會產生同檔名的HTML檔案 sample.html

預設情況都是轉成html5，並搭配css3，如果想要轉成其他格式，可以加上 -b(--backend) 來指定：

// for *.xml
asciidoctor -b docbook sample.adoc

Custom Theme

預覽剛剛的 sample.html ，發現除了標題、內文等會自動加上顏色或背景，是預設套用的 css3成果：

可利用自訂的 css 來美化頁面，以 asciidoctor-skins 寫好的主題套用作為範例。下載：

git clone https://github.com/darshandsoni/asciidoctor-skins.git

重新輸出時，-a(--attribute) 加上 css 的路徑：

asciidoctor -a stylesheet=./asciidoctor-skins/css/notebook.css sample.adoc

// or
asciidoctor -a stylesheet=notebook.css -a stylesdir=./asciidoctor-skins/css sample.adoc

開啟畫面會套用新的 stylesheet，如下：

常用參數

除了上面提到的 -a 和 -b ，其他常見的選項：
1. 輸出檔名 -o

// -o, --out-file
asciidoctor sample.adoc -o mypage.html

2. 輸出路徑 -D

// -D, --destination-dir
asciidoctor sample.adoc -D pages

輸出檔案會在資料夾 /pages 內。

3. 僅輸出內容 -s

// -s, --no-header-footer
asciidoctor sample.adoc -o mypage.html

只會輸出html中 <body> 標籤裡的內容，方便用於嵌入式頁面。

更多參數可參考：
https://asciidoctor.org/docs/user-manual/#document-conversion

2020年5月1日星期五

ubuntu18 + python2 文件編輯 AsciiDoc 安裝說明

基本上 AsciiDoc 已經停止更新，2017年已經發布了最終版本，並表示不再更新，當然 asciidoc 仍可繼續使用，直到停止支援 python2。既然都明寫建議用戶轉移使用 Asciidoctor(底層是Ruby) 或支援 Python3 的 asciidoc-py3，以下安裝步驟僅作為紀錄。

安裝之前請先確保主機已經安裝了Python(版本2.4以上)，因為安裝的腳本是用Python寫的，多數的linux系統都已經內建，所以可以直接開始按照指令安裝asciidoc。

以下操作環境為ubuntu 18.04(server)，目前ubuntu 20.04 LTS （2020/04 - 2025/04）為最新 LTS 版，但不影響下面的操作：

方法一

Step1. 下載原始碼

透過git下載原始碼，選用的版本為8.6.9

cd /bin
git clone https://github.com/asciidoc/asciidoc asciidoc-8.6.9

cd asciidoc-8.6.9
git checkout 8.6.9

Step2. 綁定指令

哈囉

(A) 綁定指令

ln -s /bin/asciidoc-8.6.9/asciidoc.py /bin/asciidoc
ln -s /bin/asciidoc-8.6.9/a2x.py /bin/a2x

(B) 編譯

autoconf
./configure
make
sudo make install

方法二
更快速的方法，可直接透過AsciiDoc Debian package安裝，指令：

apt install asciidoc

Official Site: http://asciidoc.org/

2020年5月28日 星期四