hatakoya memo

AsciiDoc

ref:
https://qiita.com/hbsnow/items/88e1414ac97501af17ff

環境構築

https://github.com/asciidoctor/docker-asciidoctor

Docker で PDF 出力

docs/index.adocを PDF 化しdist/に出力する例：

# 日本語を利用する場合は`-a scripts=cjk -a pdf-theme=default-with-fallback-font`を設定する
docker run -it --rm \
  --mount type=bind,source=docs/,target=/documents/ \
  --mount type=bind,source=dist/,target=/dist \
  asciidoctor/docker-asciidoctor:1.0.0 \
  asciidoctor-pdf -r asciidoctor-diagram -a scripts=cjk -a pdf-theme=default-with-fallback-font -D /dist index.adoc

日本語を使う場合は、Fallback Fonts の設定をする。 Ref:
https://github.com/asciidoctor/asciidoctor-pdf#support-for-non-latin-languages

オリジナルのテーマやフォントを適用する

FROM asciidoctor/docker-asciidoctor:1.0.0

WORKDIR /usr/lib/ruby/gems/2.5.0/gems/asciidoctor-pdf-1.5.0.rc.3/data
# フォントの追加
RUN cp <.ttfファイル> fonts/
# テーマの追加
RUN cp <.ymlファイル> themes/

ENTRYPOINT [ "sh" ]

VSCode

必要な拡張機能。

  • joaompinto.asciidoctor-vscode

settings.jsonで asciidoctor-kroki`を有効にすると、plantUML もプレビューされるようになる。

{
  "asciidoc.use_kroki": true
}

文法

Ref:
http://asciidoc.org/userguide.html

リスト

順序なしは*、順序付きは.子リストは**のように書く。

変数

:name: hoge

{name}

別の.adocを読み込み

include::hoge.adoc[]

リンク

link:http://example.com[hoge]

テーブル

autowidthを付けると列幅を内容に合わせてくれる。

[options='header,autowidth']
|===
|1-1|2-1|3-1

|1-2
|2-2
|3-2

|1-3
|2-3
|3-3
|===

Admonition

  • NOTE
  • TIP
  • IMPORTANT
  • CAUTION
  • WARNING
[CAUTION]
====
警告メッセージはここに。
====

PluntUML の読み込み

.Include
plantuml::../puml/hoge.puml[]

Asciidoctor Gradle Plugin

https://asciidoctor.org/docs/asciidoctor-gradle-plugin/

build.gradle

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1'
    }
}

plugins {
    id 'org.asciidoctor.convert' version '1.5.8'
}

repositories {
    mavenCentral()
}

asciidoctor {
    requires = ['asciidoctor-diagram']
    backends = ['html5']
    sourceDir = file("docs")
    outputDir = file("${buildDir}")
    attributes = [
            'imagesdir': './images'
    ]
}

次のコマンドでビルドできる。 ```bash ./gradlew asciidoctor


## CSV, TSCをテーブルに変換

次のディレクトリ構成とする。

docs index.adoc csv table.csv tsv table.tsv


TSVとCSVをインポートできる。
```adoc
TSVの読み込み。
[format="tsv", options="header"]
|===
include::../tsv/table.tsv[]
|===

CSVの読み込み。
[format="csv", options="header"]
|===
include::../csv/table.csv[]
|===

ソースコード参照

次のディレクトリ構成とする。

docs
  index.adoc
src
  test.sql

index.adocは次のように書く。

[source,sql]
----
include::../src/test.sql[]
----

Gradle + plantUML + livereload で環境構築

プロジェクトを作成する。

gradle init

build.gradleを書く。

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
    id 'org.kordamp.gradle.livereload' version '0.2.1'
}

group = 'com.example'

dependencies {
    asciidoctor 'org.asciidoctor:asciidoctorj-diagram:1.5.8'
}

asciidoctor {
    requires = ['asciidoctor-diagram']
    backends = ['html5']
    sourceDir = file("docs/adoc")
    outputDir = file("${buildDir}")
    attributes = [
            'imagesdir': './images',
            'doctype': 'book',
            'revnumber': project.version,
            'source-highlighter': 'coderay',
            'sectanchors': '',
            'toc': 'left',
            'toclevels': '2'
    ]
}

liveReload {
    docRoot asciidoctor.outputDir.canonicalPath
}

.adocファイルを作る。

mkdir docs
echo 'Hello world' > docs/adoc/index.adoc

ビルドする。

./gradlew asciidoctor

Markdown と比べた場合の利点

  • 標準で細かい表現ができる 表のセル結合や目次生成など。

ベストプラクティス

https://asciidoctor.org/docs/asciidoc-recommended-practices/

← DotFiles →