はてなブログをAsciiDocで書く方法

f:id:takamints:20190521164525j:plain
photo credit: InstructionalSolutions Keyboard and Blank Paper via photopin (license)

はてなブログをAsciiDocで書けないものかとやってみたらなんとかなった。

前回記事(「AsciiDocのテーブルで行のヘッダを指定する方法」)でコードブロックのAsciiDocをプレビューするため書き殴ったJavaScriptを整理してご紹介しております。

実際には、はてなブログだけじゃなくて他社のブログやウェブサイトでも使えるはずです。

お世話になったブログはこちら（↓）：

ytyaru.hatenablog.com

「ダメだった」となっていますが、そもそも asciidoctor.js（@asciidoctor/code の以前のバージョン）を知ったのが、このブログでしたので。感謝っ！

Miceroux(ﾐｾﾙｰ)でAsciiDocを変換する
Micerouxのスクリプトを読み込む一般的な方法
はてなブログでMicerouxを読み込む方法
APIリファレンス
PREに書いたAsciidocをプレビューする
Markdownのコードブロックをプレビューする
コンテンツそのものをAsciiDocで書くには？
制限事項
機能拡張の可能性
あとがき

沈黙のWebライティング —Webマーケッターボーンの激闘—〈SEOのためのライティング教本〉

posted with amazlet at 19.05.21

松尾茂起
エムディエヌコーポレーション (2016-11-01)
売り上げランキング: 177

Amazon.co.jpで詳細を見る

Miceroux(ﾐｾﾙｰ)でAsciiDocを変換する

Micerouxは npm @asciidoctor/core を使ってHTML要素内のAsciiDocをレンダリングして表示するJavaScriptです。

takamin.github.io

スクリプトは（Webpackで）バンドルしており、以下のURLに置いていますので、誰でも御自由に使ってください。使い方は以降で説明しております。

https://takamin.github.io/js/miceroux.min.js

Micerouxのスクリプトを読み込む一般的な方法

SCRIPTタグでMicerouxを読み込んで、特定のセレクターでHTML要素を指定してAsciiDocを変換して表示します。

普通のWEBページでは、以下の２つのSCRIPTを、できればBODYの最後に貼り付けます。ページが読み込まれたときに一回だけ動作すればOKです。

<script type="application/javascript"
    src="https://takamin.github.io/js/miceroux.min.js">
</script>
<script type="application/javascript">
    Miceroux.asciidoc("pre.code.miceroux-asciidoc");
    Miceroux.asciidoc("script[type='text/asciidoc']");
</script>

はてなブログでMicerouxを読み込む方法

はてなブログではSCRIPTタグをBODYの最後に置けません（よね？）なのでダッシュボードから[設定]-[詳細設定]で編集できるHEADの中に以下のコードを貼り付けます。

<script type="application/javascript"
    src="https://takamin.github.io/js/wait_jquery.js">
</script>
<script type="application/javascript"
    src="https://takamin.github.io/js/miceroux.min.js">
</script>
<script type="application/javascript">
$(()=>{
    Miceroux.asciidoc("pre.code.miceroux-asciidoc");
    Miceroux.asciidoc("script[type='text/asciidoc']");
});
</script>

あたかもjQueryを使っているように見えますが、はてなブログではjQueryがBODYの最後あたりで読み込まれますので、実はHEAD内でjQueryは使えません。ここで使っている $ は最初のSCRIPTタグで読み込んでいる wait_jquery.js で定義している関数です。この偽物の$で、与えられたFunctionを貯めておいて、jQueryが読み込まれたあと順次呼び出しているのです。この件については以前以下のページで詳しく書いているので参考にしてください。
※ 何が行われているのか気にならなければ上のコードを貼り付けるだけでOKだと思います。

takamints.hatenablog.jp

APIリファレンス

PREに書いたAsciidocをプレビューする

AsciiDocのソースコードをコードブロックで見せつつ、その内容を変換して表示させるには、PREタグのclass属性に code と miceroux-asciidoc を設定します。要するに上の方で書いてたHTML要素のセレクタに従ったclassをつければよいってことです。

PREで書く例：

=== 基本的な書き方
段落を記載するのに特別なマークアップは不要です。
１行から複数行に渡り連続して記述するだけです。

新しい段落を始める時は、最低１行の空白行を入れてください。

Markdownのコードブロックをプレビューする

マークダウンのコードブロックもPREに変換されますね。 Markdownのシンタックスハイライト用の言語名に miceroux-asciidoc を指定してください（以下の例）。

```miceroux-asciidoc
～ AsciiDocドキュメント ～
```

こうすることで、HTML的には前述のPREタグの例のように表現されます。

以下はコードブロックのAsciiDocを変換した例です。

太字、イタリック、モノスペース
結果を表示する
フォーマット対象文字列の左右にスペースがある場合は、１つの演算子で囲みます。 +
スペースが無い場合(文章の途中、単語の一部)などの場合は、2つの演算子で囲みます。

*太字の語句* と **太**字の文**字**

_イタリックの語句_ と __イタ__リックの文__字__

*_太字のイタリックの語句_* と **__太字のイタ__**リックの文**__字__**

`モノスペースの語句`と``モノ``スペースの文``字``

`*モノスペースの太字の語句*` と ``**モノ**``スペースの太字の語``**句**``

`_モノスペースのイタリックの語句_` と ``__モノ__``スペースのイタリックの文``__字__``

`*_モノスペースの太字のイタリックの語句_*` と ``**__モノ__**``スペースの太字のイタリックの``**__文字__**``

コンテンツそのものをAsciiDocで書くには？

文章そのものをAsciiDocで書くとき、ソースは表示したくありませんから、SCRIPTタグに書けばよいです。 type属性をtext/asciidocとする必要があります。

<script type="text/asciidoc">
=== 改行
結果を表示する
プラスを行末に指定すると改行とみなされます。 +
ルビーの色は赤です。 +
トパーズの色は青です。

[%hardbreaks]
段落にhardbreaksを指定するとテキスト上での改行が、
そのまま改行として表示されます。
ルビーの色は赤です。
トパーズの色は青です。
</script>

制限事項

AsciiDocではH1に相当する見出しは文書名を表すので、画面に表示されません。これは @asciidoctor/core の仕様のようです。
NOTE: などの注釈で、画像としてのアイコンが表示されません。
リソースを必要とするスタイル指定などの機能については十分確認していません。@asciidoc/core でできることは全て可能と思いますが、詳細は未検証です。
上に記載した変換例では変換後の文書が赤い枠で囲まれていますが、これは説明用のスタイルです。本来は通常のHTMLと境目なく表示されます。

機能拡張の可能性

PREとSCRIPTの他にTEXTAREAも変換できると思います。が、今の所編集結果の自動更新機能は提供していません。 changeイベントなどで実装するのは可能だと思います。

あとがき

これ作ったのは「ブログ記事のテーブルだけでもAsciiDocで書きたいものだ」というのが発端でした。

Markdownのテーブルは、行を1行に納めないといけないのが書きにくさの要因かも。シンプルなテーブルなら AsciiDoc のほうが格段に楽ですよね。細かいことをしようとすれば、それなりに複雑になるけど、列幅の指定やヘッダの指定程度であれば覚えてしまえば楽なもんです。セルの結合もできますしね。

その他、定義リスト（HTMLの <dl>, <dt>,<dd>）もAsciiDocのほうが便利ですね。MarkdownではHTML＆CSSを駆使して書くしか無い。脚注や注釈、あと目次も強力。良いところ把握して使っていきたいものですなー。

銀の弾丸

プログラミングに関して、いろいろ書き残していければと思っております。