概要
- Markdownからの変換手法
  - 変換前提のMarkdownの書き方について
  - 置換でタイトルの"#"を"="に変更
- workflowの定義

概要

MarkdownAsciidocのきれいな書類をMarkdownで書く
GitHub Actionsで作成してホスティングする

下記記事のGitHub Actions版だと思えば良いです。

ossyaritoori.hatenablog.com

下記に出来上がった書類のサンプルを載せます。

https://yoshiri.github.io/MarkdownToAsciidocToHTML_CI/sample.html

Markdownからの変換手法

ここではMarkdownで書いた文をAsciidocに変換します。

qiita.com

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

引数の詳細などは下記を参照すると良いです。（本当は英語版サイトのほうがもっと良い。）

sky-y.github.io

変換前提の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`のときの書き方）

理由は次で説明します。

--shift-heading-level-by=-1を用いた時の挙動について

pandocで下記のようなマークダウンを変換した場合，レベルを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の定義

サンプルリポジトリをおいておきます。

github.com

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

以上！