GitHub Actionを使ってMarkdownで書いた文書をAsciidocを介したHTMLに変換する

8582 ワード
GitHubActions Markdown asciidoc Markdown テキストリンク

概要

  • Markdownで書いた文書をGitHubのリモートリポジトリにPushしてHTML文書を作る
    • GitHub Actions上のPandocでMarkdown → Asciidoc変換
    • GitHub Actions上のAsciidoctorで Asciidoc → HTML変換
    • ついでにホスティングしてもらってすぐに結果を見れるようにする

こんな文章の見た目になります。

背景

AsciidocはMarkdownのような書きやすさとLatexのような描写力をちょうどいいとこ取りしたようなマークアップ言語です。

Asciidocで生成されるHTML書類にはPlantUMLが載せられたり，レイアウトを細かにいじったりできるので仕様書などの生成に比較的向いているのですが，

如何せんMarkdownと文法がごっちゃになったりして覚えるのがいろいろ面倒臭いという問題があります。


そこで，ローカルでMarkdownで書いてしまってその後GitHub Actionsでリモートホストに変換からホスティングまでよろしくやってもらうことにしました。

先行研究

以前MarkdownからAsciidocに変換してHTMLにするのをローカルの環境でやっており，ある程度個人のブログにまとめています。

変換結果の確認などは下記のリポジトリで行っているところです。

一方，それでもDockerの環境やらなにやらを用意して毎回長ったらしいコマンドを打つのが面倒なので今回の記事に至ります。

GitHub Actionsの設定

GitHub Actionsを使うのは初めてなので最適解かどうかはわかりませんが，ひとまず動くリポジトリを下記に残しておきます。

ざっくりとした動作原理

きちんと語れるほど詳しくないですが.github/workflows/hoge.ymlというファイルを設定することでActionsを設定出来ます。

今回は変更がPushされたときに起動するアクションを設定しました。

流れとしては，下記のようになっています。

  • Github Workspaceにリポジトリのファイルをチェックアウト
  • markdown -> asciidoc 変換 by Pandoc on Docker
  • asciidoc -> html 変換 by asciidoctor Action
  • 生成物をbuildフォルダに移動
  • build folderの中身をgh-pagesブランチにPush （ 参考）

そして実際のコードは以下のようになっています。

# 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: Markdown To Asciidoc
      uses: docker://pandoc/core:2.9
      with:
        args: sample.md --to asciidoctor -o sample.adoc
    # 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

詳細：Markdown から Asciidoc変換

Kramdocを使ってもいいですが，PandocのActionがあったのでPandocを用いました。

本来のコードはだいたい以下の通りになります。

pandoc sample.md --to asciidoctor -o sample.adoc

スペース1つでも改行がされてしまうなどの不具合？がありますが概ね意図通りの変換担っている気がします。

詳細：AsciidocからHTML変換

こちらはasciidoctorコマンドを用いて変換しています。

asciidoctor sample.adoc -r asciidoctor-diagram -a allow-uri-read -a data-uri -a toc=left

それぞれのオプションの意味は下記のとおりです。こちらはほぼいじる必要はないかと思います。

  • -r asciidoctor-diagram：PlantUMLなどの図を貼れるようにする
  • -a allow-uri-read：ページ外からのコンテンツ有効化
  • -a data-uri：画像などのデータのhtmlへの埋め込み
  • -a toc=left：左に目次をつける

TODO

他にもこういうことができるべきなどあればコメント・意見くださると喜びます。

  • 数式やPlantUMLなどが正しくはれるかチェック
  • Pandocの変換部分のチェック
  • ブランチごとに別のhtmlファイルをホスティングできると嬉しい（文章でブランチを着る時用）

参考