プロダクトのドキュメントをMarkdownからAsciiDocに移行した

これまでGradle SSH PluginやGroovy SSHのドキュメントをGitHub Flavored Markdown（GFM）で書いていましたが、AsciiDocに移行してみました。やったことを記事に残しておきます。

動機

これまでソースコードリポジトリとドキュメントリポジトリを別々に管理していたため、機能追加や仕様変更を行うたびに両方のリポジトリを変更する必要がありました。このため、一つのPull Requestでコードとドキュメントの変更を確認できない、ドキュメントの変更を忘れるといった問題がありました。

そこで、ソースコードとドキュメントのリポジトリを統合することにしました。統合にあたり、せっかくなのでドキュメントを表現力の高いAsciiDocに移行することにしました。

GradleでAsciiDocをビルドする

Gradle SSH PluginやGroovy SSHではビルドツールにGradleを採用しているため、ドキュメントもGradleでビルドするようにしました。 ドキュメントのファイル群は /src/docs/asciidoc に配置して、拡張子を .adoc にしました。 ビルドスクリプトには以下を追記しました。

plugins {
    id 'com.github.johnrengelman.shadow' version '1.2.0'
}

asciidoctor {
    attributes(
        'source-highlighter': 'coderay',
        toc: 'right',
        numbered: true,
        icons: 'font',
    )
}

MarkdownをAsciiDocに移行する

以下の手順で移行しました。

• リンクを [name](http://url) から http://url[name] に変える
• セクションタイトルの行頭を *から = に変える
• 表組みの記法を変える
  • 手作業なので面倒
  • GFMはデフォルトで列幅自動調整だったけど、Asciidocは均等幅になるため、表組みのオプションで autowidth を指定した
• やむを得ずHTMLをベタ書きしていた部分は ++++ （パススルー）に変える

MarkdownとAsciiDocの違いは下記を参考にしました。

github.com

細かい記法はやはり公式ドキュメントが役に立ちます。

asciidoctor.org

完成版

AsciiDocに移行後のドキュメントはこちらにあります。

gradle-ssh-plugin.github.io