概要
下記記事のGitHub Actions版だと思えば良いです。
下記に出来上がった書類のサンプルを載せます。
https://yoshiri.github.io/MarkdownToAsciidocToHTML_CI/sample.html
Markdownからの変換手法
ここではMarkdownで書いた文をAsciidocに変換します。
MarkdownからAsciidocへの変換はPandocとKramdocの2択があります。
- Pandoc
- 言わずとしれた万能変換ツール
- 🙆数式などの変換がちゃんとしている
- 🙅タイトルへの変換
- Kramdoc
- Asciidoctorの開発側が開発した変換ツール
- 🙆章立てなどがきれいに変換される
- 🙅数式や一部書式が正しく変換されない
ここではPandocを採用します。（数式の書きにくいドキュメントはありえないので。）
ここで，Pandocで用いるコマンドを下記に示します。(DockerコマンドなのでPandoc環境がある人は適当に読み替えてください)
wsl docker run --rm -v $(pwd):/data pandoc/core: sample.md --to asciidoctor -o sample_pandoc.adoc --shift-heading-level-by=-1
引数の詳細などは下記を参照すると良いです。（本当は英語版サイトのほうがもっと良い。）
変換前提のMarkdownの書き方について
基本的な書き方はうまいこと変換されますが，気をつけなければ行けないのは章立てです。
通常の書き方をすると下記のようになると思います。
# 1章 ## 1-1節 ## 1-2 節 # 2章 ## 2-1節 ### 2-1-1節 ...
本記事で紹介する変換法を用いる場合文章は下記のように書くことを推奨します。 AsciidocのLevel1はHTMLのタイトル用であり，章がLevel2からスタートしていることに起因します。
# 文書タイトル ## 1章 ### 1-1節 ### 1-2 節 ## 2章 ... このように一つずつずらす。
または，マークダウンで見た時に不格好になるのが気にならなければ下記のようにかくのも良いでしょう。
= 文書タイトル ## 1章 ### 1-1節 ### 1-2 節 ## 2章 ... （上記は`--shift-heading-level-by=-1`のときの書き方）
理由は次で説明します。
pandocで下記のようなマークダウンを変換した場合，レベルを1段下げます。--shift-heading-level-by=-1を用いた時の挙動について
# 文書タイトル ## 1章 ### 1-1節
下記のようにAsciidocでは=が#のような役割を持ちます。
== 文書タイトル === 1章 ==== 1-1節
これに対して--shift-heading-level-by=-1を引数に加えることでレベル下げをキャンセルできます。 できるのですがタイトルのブッキングを避けるために下記のような結果を生成します。
文書タイトル <- 本当は"="から始まってほしい == 1章 === 1-1節
これを避けるもっとも手っ取り早い方法は最初からタイトルの装飾を"#"から"="に書き換えて置くことです。
置換でタイトルの"#"を"="に変更
タイトルの装飾を"#"から"="に書き換えて置くことで上記の問題は解決しますが，Markdownでこれを書くのは面倒。
ということで，GithubなどのCIの時点でタイトルの装飾を変えれば良いです。
具体的には，sedコマンドを用いて 文章の最初に出てきた"# "のを"= "に変えます。（タイトルはほぼ文章の最初に来るはずなので）
コマンドはこちら。
sed -ie '0,/# / s/# /= /' sample.md
workflowの定義
サンプルリポジトリをおいておきます。
workflowは下記のような内容です。
# This is a basic workflow to help you get started with Actions
name: CI
# Controls when the action will run.
on:
# Triggers the workflow on push or pull request events but only for the master branch
push:
branches: [ master ]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# asciidoc to html
asciidoctor_job:
# The type of runner that the job will run on
runs-on: ubuntu-latest
name: Build AsciiDoctor
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- name: Check out code
uses: actions/checkout@v2
- name: Fix Title Level Issue
run: sed -ie '0,/# / s/# /= /' sample.md
- name: Markdown To Asciidoc
uses: docker://pandoc/core:2.11
with:
args: -f markdown+east_asian_line_breaks sample.md --to asciidoctor -o sample.adoc --wrap=preserve --verbose --shift-heading-level-by=-1
# Output command using asciidoctor-action
- name: Build AsciiDoc step
id: documents
uses: Analog-inc/asciidoctor-action@master
with:
shellcommand: "asciidoctor sample.adoc -r asciidoctor-diagram -a allow-uri-read -a data-uri -a toc=left"
# Use the output from the documents step
- name: move deploy files
run: |
mkdir build/
mv sample* build/
ls build
- name: deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build
publish_branch: gh-pages
以上！
