Asciidocから変換されるHTMLをS3 Hostingに自動デプロイする

背景

• プロジェクトリリース前に、色々なユーザガイドなどを公開しないといけない
• wordを書いてPDFに変更することが面倒
• PDFの読むことはダウンロードの前提になってしまう

概要

• 標準ドキュメントAsciidocを作って、PDFやHTMLへ簡単に変換できる
• AWS S3 Hosting機能を利用して速めにドキュメントを公開できる

詳細

Asciidocとは

• AsciiDoc
• Asciidoctor 文法クイックリファレンス(日本語訳)

AsciidocからPDFやHTMLへ変換する方法

• asciidoc gem packageをインストールして簡単に変換できる

gem install asciidoctor
gem install asciidoctor-pdf

asciidoctor procedure/document_source.adoc -o dest/document_dest.html

openapi yamlファイルからHTMLへ変換する方法

• openapi-generator-cliでopenapi yamlファイルからAsciidocへ変換できる

openapi-generator-cli generate -i api/document_source.yaml -g asciidoc -o temp
asciidoctor temp/index.adoc -o dest/document_dest.html

S3 Hosting作成

• template.ymlで速めに作成できる

# ------------------------------------------------------------#
# Input Parameters
# ------------------------------------------------------------# 
Parameters:
  WebsiteDomainName:
    Type: String

Resources:
# ------------------------------------------------------------#
#  S3 Bucket
# ------------------------------------------------------------#        
# Bucket
  Bucket:
    Type: "AWS::S3::Bucket"
    Properties:
      BucketName: !Ref WebsiteDomainName
      AccessControl: PublicRead
      WebsiteConfiguration:
        IndexDocument: index.html

  BucketPolicy:
    Type: "AWS::S3::BucketPolicy"
    Properties:
      Bucket: !Ref Bucket
      PolicyDocument:
        Statement:
        - Action: "s3:GetObject"
          Effect: Allow
          Resource: !Sub "arn:aws:s3:::${Bucket}/*"
          Principal: '*'
          Condition: 
            IpAddress: 
              "aws:SourceIp": 
                - "xxx.xxx.xxx.xxx/xx"

codebuildでデプロイする

 version: 0.2
	 
 phases:
   install:
     on-failure: ABORT
     runtime-versions:
       nodejs: latest
       ruby: latest
     commands:
       - npm install @openapitools/openapi-generator-cli -g
       - gem install asciidoctor
       - gem install asciidoctor-pdf
 
   build:
     commands:
       - openapi-generator-cli generate -i api/document_source.yaml -g asciidoc -o temp
       - asciidoctor temp/index.adoc -o dest/document_dest.html
       - asciidoctor procedure/document_source.adoc -o dest/document_dest.html
       - cp -rp procedure/images/. dest/images/.
 
   post_build:
     commands:
       - aws s3 sync --exact-timestamps ./dest/ s3://WebsiteDomainName/ --exclude ".*"