개요

Markdown에서 작성한 문서를 GitHub 원격 리포지토리에 푸시하여 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 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

스페이스 하나라도 개행이 되어 버리는 등의 문제? 있습니다만 대체로 의도대로의 변환 담당하고 있는 것 같습니다.

세부사항: 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 파일을 호스팅 할 수 있다면 기쁩니다 (문장으로 브랜치를 입을 때)

참고

Asciidoc 입문

문법 참조