From a84908b7e8a0e2423afd6b836eccf27a420270b4 Mon Sep 17 00:00:00 2001 From: nsfisis Date: Wed, 20 Sep 2023 19:56:52 +0900 Subject: feat(blog/nuldoc): change content format from DocBook to NulDoc --- .../2023-03-10/rewrite-this-blog-generator.ndoc | 94 +++++++++++++++++++++ .../2023-03-10/rewrite-this-blog-generator.xml | 97 ---------------------- 2 files changed, 94 insertions(+), 97 deletions(-) create mode 100644 vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.ndoc delete mode 100644 vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.xml (limited to 'vhosts/blog/content/posts/2023-03-10') diff --git a/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.ndoc b/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.ndoc new file mode 100644 index 00000000..0959117f --- /dev/null +++ b/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.ndoc @@ -0,0 +1,94 @@ +--- +[article] +title = "このブログのジェネレータを書き直した" +description = "このブログのジェネレータを書き直したので、やったことを書き記しておく。" +tags = [] + +[[article.revisions]] +date = "2023-03-10" +remark = "公開" +--- +
+
+ はじめに +

+ このブログを構築するシステムを書き直したのは 2度目である。 + 元々立ち上げた当初は、静的サイトジェネレータである Hugo を使っていた。 + それを Asciidoctor にいくつかのカスタムを加えた自前のジェネレータに移行したのが 2022年の11月ごろだ。 + そして今回、スクラッチから書いた Deno 製のジェネレータに移行した。 +

+

+ この記事では、移行の理由などを (主に将来の私へ向けて) 書き記しておく。 +

+
+
+ Hugo から Asciidoctor へ +

+ 最初に断っておくと、Hugo は大変に優れた静的サイトジェネレータである。移行の理由の大半は、自分でジェネレータを書きたかったからに他ならない。 + 実のところ、この記事を執筆している現在、自作ジェネレータは Hugo よりも機能が劣っている。 + 例えば、Hugo を使っていたころはサポートしていた RSS フィードの生成は、まだ実装できていない。 +

+

+ 移行先のフォーマットとして AsciiDoc を選んだのは、Markdown よりも表現力に優れるからである。Markdown は広く使われている軽量マークアップ言語だが、以下のような欠点を持つ。 +

+

+

    +
  • CommonMark では機能が貧弱である (例: 脚注、id 属性の付与)
    • +
  • 拡張記法に実装間で互換性がない
    • +
  • メタデータ (公開日など) を埋め込む統一された方法がない
    • +
+

+

+ AsciiDoc は Markdown に比べると普及していないが、上記の欠点は克服している。 +

+

+

    +
  • ブログを書くのに十分な表現力がある
    • +
  • フォーマットを拡張するときの記法があらかじめ定められている
    • +
  • メタデータを埋め込む統一された方法がある
    • +
+

+

+ なお、Hugo は AsciiDoc もサポートしているのだが、AsciiDoc を使う場合 Asciidoctor を別途インストールする必要があり、それならば最初から Asciidoctor でよかろうと移行を決めた。 +

+
+
+ Asciidoctor から自前のジェネレータへ +

+ AsciiDoc は良いフォーマットだが、私には 1点不満があった。それは、高い表現力を担保するために記号が使い倒されており、エスケープが難しいという点だ (具体例を挙げたいのだが、何だったか覚えていない)。これは、多種多様な記号類を入力する必要のある技術ブログにとっては辛い問題である。この問題を解決するため、 +

    +
  • 表現力が高く、
    • +
  • 文法が厳密であり、
    • +
  • 簡単に実装できる
    • +
+ フォーマットが求められた。これに合致したのが、XML をベースとする DocBook (今回使っているのは、そのサブセットである Simplified DocBook) である。 +

+

+ 実は、AsciiDoc と DocBook はおおよそ互換性がある。AsciiDoc で書かれた文書は (ほぼ) 情報ロスなしに DocBook へ変換でき、逆もまたしかりである。 + よって、DocBook には、AsciiDoc と同等の表現力がある。 +

+

+ XML の文法の厳密さについては、説明するまでもないだろう。また、単純な文法であることから実装が容易であり、事実上 Asciidoctor へロックインされる AsciiDoc とは異なり、さまざまな言語で多くのライブラリが存在する。 +

+

+ 今回は、XML のパース自体も自分で書いている (これは何となく書きたかったからであり、合理的な理由があるわけではない。実装はサボりまくっているので XML のコメントが使えないといった制限がある)。 +

+

+ XML という機械処理しやすいフォーマットを選ぶことには、機械的な変換や検査といった処理がおこないやすくなるといった利点もある。 + 欠点は軽量マークアップ言語と比べて冗長であることだが、書く際は補完などを用いるのでそれほど気にならない。 + 結局のところ、技術ブログの執筆を律速するのは調査と文章の記述であり、マークアップの手段は執筆時間に大した影響を与えない。 +

+
+
+ おわりに +

+ 2度のリライトを経て、記事のフォーマットとサイトジェネレータを上から下まで掌握した。 + 今後も改善のアイデアは多数あるので、じわじわと進めていきたいところだ。 +

+

+ 最後にもう一度書くのだが、Hugo は大変に優れた静的サイトジェネレータである。 + 無駄な拘りがなければこれを使うとよい。 + 私は無駄に拘ったので、ブログの記事を書く時間を潰してブログシステムを作ってしまった。 +

+
+
diff --git a/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.xml b/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.xml deleted file mode 100644 index 9deff792..00000000 --- a/vhosts/blog/content/posts/2023-03-10/rewrite-this-blog-generator.xml +++ /dev/null @@ -1,97 +0,0 @@ - -
- - このブログのジェネレータを書き直した - - このブログのジェネレータを書き直したので、やったことを書き記しておく。 - - - - 2023-03-10 - 公開 - - - -
- はじめに - - このブログを構築するシステムを書き直したのは 2度目である。 - 元々立ち上げた当初は、静的サイトジェネレータである Hugo を使っていた。 - それを Asciidoctor にいくつかのカスタムを加えた自前のジェネレータに移行したのが 2022年の11月ごろだ。 - そして今回、スクラッチから書いた Deno 製のジェネレータに移行した。 - - - この記事では、移行の理由などを (主に将来の私へ向けて) 書き記しておく。 - -
-
- Hugo から Asciidoctor へ - - 最初に断っておくと、Hugo は大変に優れた静的サイトジェネレータである。移行の理由の大半は、自分でジェネレータを書きたかったからに他ならない。 - 実のところ、この記事を執筆している現在、自作ジェネレータは Hugo よりも機能が劣っている。 - 例えば、Hugo を使っていたころはサポートしていた RSS フィードの生成は、まだ実装できていない。 - - - 移行先のフォーマットとして AsciiDoc を選んだのは、Markdown よりも表現力に優れるからである。Markdown は広く使われている軽量マークアップ言語だが、以下のような欠点を持つ。 - - - - CommonMark では機能が貧弱である (例: 脚注、id 属性の付与) - 拡張記法に実装間で互換性がない - メタデータ (公開日など) を埋め込む統一された方法がない - - - - AsciiDoc は Markdown に比べると普及していないが、上記の欠点は克服している。 - - - - ブログを書くのに十分な表現力がある - フォーマットを拡張するときの記法があらかじめ定められている - メタデータを埋め込む統一された方法がある - - - - なお、Hugo は AsciiDoc もサポートしているのだが、AsciiDoc を使う場合 Asciidoctor を別途インストールする必要があり、それならば最初から Asciidoctor でよかろうと移行を決めた。 - -
-
- Asciidoctor から自前のジェネレータへ - - AsciiDoc は良いフォーマットだが、私には 1点不満があった。それは、高い表現力を担保するために記号が使い倒されており、エスケープが難しいという点だ (具体例を挙げたいのだが、何だったか覚えていない)。これは、多種多様な記号類を入力する必要のある技術ブログにとっては辛い問題である。この問題を解決するため、 - - 表現力が高く、 - 文法が厳密であり、 - 簡単に実装できる - - フォーマットが求められた。これに合致したのが、XML をベースとする DocBook (今回使っているのは、そのサブセットである Simplified DocBook) である。 - - - 実は、AsciiDoc と DocBook はおおよそ互換性がある。AsciiDoc で書かれた文書は (ほぼ) 情報ロスなしに DocBook へ変換でき、逆もまたしかりである。 - よって、DocBook には、AsciiDoc と同等の表現力がある。 - - - XML の文法の厳密さについては、説明するまでもないだろう。また、単純な文法であることから実装が容易であり、事実上 Asciidoctor へロックインされる AsciiDoc とは異なり、さまざまな言語で多くのライブラリが存在する。 - - - 今回は、XML のパース自体も自分で書いている (これは何となく書きたかったからであり、合理的な理由があるわけではない。実装はサボりまくっているので XML のコメントが使えないといった制限がある)。 - - - XML という機械処理しやすいフォーマットを選ぶことには、機械的な変換や検査といった処理がおこないやすくなるといった利点もある。 - 欠点は軽量マークアップ言語と比べて冗長であることだが、書く際は補完などを用いるのでそれほど気にならない。 - 結局のところ、技術ブログの執筆を律速するのは調査と文章の記述であり、マークアップの手段は執筆時間に大した影響を与えない。 - -
-
- おわりに - - 2度のリライトを経て、記事のフォーマットとサイトジェネレータを上から下まで掌握した。 - 今後も改善のアイデアは多数あるので、じわじわと進めていきたいところだ。 - - - 最後にもう一度書くのだが、Hugo は大変に優れた静的サイトジェネレータである。 - 無駄な拘りがなければこれを使うとよい。 - 私は無駄に拘ったので、ブログの記事を書く時間を潰してブログシステムを作ってしまった。 - -
-
-- cgit v1.2.3-70-g09d2