HN 日本語サマリー

← 一覧へ戻る
プログラミング

Gleam、Org-Mode、Pandocを使ったブログ

Blogging with Gleam, Org-Mode and Pandoc (byzantine-systems.github.io)

82 pointsby schonfinkel18 コメント

要約

この記事では、EmacsとOrg-modeを中心に、Gleam、Pandoc、d2などのツールを組み合わせて静的サイトを構築する手法を紹介しています。Org-modeの強力な機能とEmacsのエコシステムを活用し、コードブロックの実行や図の生成までをシームレスに行うことで、開発者がコンテンツ作成に集中できる環境を目指しています。

全文翻訳

Gleam, Org-mode, Pandoc を使ったブログ執筆

私はプログラムを構成する上で、非常に興奮するような方法を見つけました。事実、私の熱意はあまりにも大きいので、読者には、大きな光を見たばかりだと信じている狂信者のたわごととして、私がこれから言うことの多くを割り引くように警告しなければなりません。

(Knuth 1984, 1)

Byzantine Systems の最初のブログ記事へようこそ。Org-mode を中心にウェブサイトを構築するのはこれが初めてではありません。私はすでに自身のブログで Emacs 最大主義への道 について書いており、そこでは Emacs、いくつかの疑わしいスクリプト、そして Nix がすべてをまとめていました。今回は、機能していた部分(すべて Emacs で書くこと)を維持しつつ、公開側の部分をより小さく、型付けされ、理解しやすいものにしたいと考えました。

最終的な実験では、以下のツールを使用します。

  • Orgmode をソースフォーマットとして、Emacs を執筆環境として使用。
  • d2 を宣言的な図の作成に使用。
  • Babel を Org をさらに強力にするために使用。
  • Pandoc を堅牢で成熟したコンバーターとして使用。
  • Nix、flakes、devenv をビルド環境を固定するために使用。
  • Gleam と Blogatto を、小さく型付けされた静的サイトパイプラインのために使用。
  • Lustre を、別のテンプレート言語を導入せずに周囲の HTML を定義するために使用。

最後の2点は、単純な静的ページには過剰に見えるかもしれませんが、すべての投稿をリストするページをどのように作成するかで判断していただければと思います。それは単なる Gleam 関数で、Lustre 要素を返します。

投稿インデックスは、通常の型チェックされた Gleam コードです。

pub fn posts_page(posts: List(Post(msg))) -> Element(msg) {
  let sorted = list.sort(posts, fn(a, b) { timestamp.compare(b.date, a.date) })

  layout("Posts", [
    html.h2([], [html.text("Posts")]),
    case sorted {
      [] -> html.p([], [html.text("No posts yet.")])
      _ -> html.ul([], list.map(sorted, post_link))
    },
  ])
}

このブログ記事の tl;dr バージョンは以下のようになります。

[画像: このブログ記事の tl;dr バージョンを示す図]

私は Org ドキュメントにのみインタラクションします。Nix は、残りのパイプラインを快適に、問題なく機能させるための接着剤です。

もう一つの重要な詳細ですが、前の図は Emacs 内で生成されました。私は「コードとしての図」という考えを生かし続けたいと思っており、現時点では d2 がうまく機能しています。これは、Emacs のマジックなしで図のコードがどのように見えるかを示しており、結果(画像)のみを保持しています。

direction: right

style.fill: "#ffffff"

# Default node styling
*.shape: rectangle
*.style: {
  border-radius: 8
  stroke-width: 2
  font-size: 12
}

# Default edge styling
(* -> *)[*].style: {
  stroke: "#64748b"
  font-color: "#475569"
  stroke-width: 2
  font-size: 10
}

emacs: "1. Emacs + Orgmode\nWrite raw content (.org)" {
  style: {
    fill: "#f3e8ff"
    stroke: "#a855f7"
    font-color: "#581c87"
  }
}

pandoc: "2. Pandoc + plugins\nConvert Org to Markdown (.md)" {
  style: {
    fill: "#e0f2fe"
    stroke: "#0284c7"
    font-color: "#075985"
  }
}

blogatto: "3. Blogatto\nGenerate final HTML" {
  style: {
    fill: "#dcfce7"
    stroke: "#16a34a"
    font-color: "#14532d"
  }
}

emacs -> pandoc: Export
pandoc -> blogatto: Build

なぜすべてを Emacs の中に保つのか?

中程度に関連しますが、私の親友である Marcos Magueta は、GNU Shepherd はより良いコンピューティング時代のための抽象化である という興味深いビデオを作成しました。そこで彼は BLOAT(肥大化) という、UNIX の世界では非常に嫌われている言葉について論じています。しかし、ほとんどの人は以下なしでそれを行っています。

  • BLOAT が本当に何であるかを正しく定義すること。
  • GOOD BLOAT(良い肥大化) が何をもたらすかを知ることなしに。

Emacs は、UNIX の哲学的な観点から見ると、純粋なブロートです。確かに、Emacs は UNIX の「一つのことをうまくやる」という原則に従っていません。実際にはそれが良いとさえ主張できます。統一された環境の欠如は、結局ユーザーランドの BLOAT を引き起こすだけです。この定義により、Emacs は 良いブロート となるでしょう。

一貫性は、標準を普及させる中央機関による集中的な努力を必要とします。Macintosh 上のアプリケーションは、Apple が公開したガイドブックに従っているため一貫性があります。Unix ユーティリティには、そのような機関は存在しませんでした。その結果、一部のユーティリティはダッシュで始まるオプションを使用し、一部は使用しません。一部は標準入力を読み込み、一部は読み込みません。一部は標準出力を書き込み、一部は書き込みません。一部は世界書き込み可能なファイルを作成し、一部は作成しません。一部はエラーを報告し、一部は報告しません。一部はオプションとファイル名の間にスペースを置き、一部は置きません。

(Garfinkle, Weise, and Strassmann 1994, 25–26 chap.2)

また、Emacs を離れることは敗北を認めることになります。私にとって、ブログ記事(またはメモ)を書くことは、単に段落を書く以上のことです。ソースコードを周りに配置したり、メモをエクスポートしたり、適切な bibtex 引用が常に機能することを望んだりします。これらのそれぞれに別のアプリケーションが必要な場合、作業は同じアイデアの断片を含むウィンドウ(または TUI)のツアーになります。長期的な目標は、最終的にすべてを Emacs の中に移動することですが、その日は今日ではありません。

なぜ Markdown ではなく Org-mode なのか?

(…) Org-mode の些細な使い方は、単なるテキスト編集に過ぎず、そこからユーザーは文書に特別なプレーンテキスト Org-mode 要素を追加し始めることができます。したがって、Org-mode は採用が容易であり、計算言語と自然言語が混在するプロジェクトの作成のための一般的なソリューションを目指しています。複数のプログラミング言語、エクスポートターゲット、ワークフローをサポートしています。

(Schulte et al. 2012, 2)

私たちはすでに Markdown を持っていますよね?それはユビキタスで、読みやすく、ほとんどすべての静的サイトジェネレーターでサポートされています。実際、このサイトは Pandoc が生成する Markdown を使用し、Blogatto がそれを消費します。私はそれを直接書くだけではありません。

その理由は、Orgmode がはるかに優れたフォーマットであり、唯一の欠点は、それを完全に楽しむには Emacs 内にいる必要があること(そしてそれは許容できるトレードオフのように思えます)です。本当に望むなら、.org は単純な軽量マークアップフォーマットのままでいることができます…または、カスタムコマンド引数と生成された結果の場所さえも備えた、Org ドキュメント内で任意のソースブロックを実行することもできます。

それが本当に強力な理由であり、私が Org メモの中に d2 図を、オンデマンドでいつでも画像を/図を再生成できるように埋め込むのが好きな理由です。それは、有名な Jupyter Notebook に非常に似た、小さく再現可能な(研究のような)環境です。

Org-mode は、Emacs をシンプルで強力なマークアップ言語で拡張し、階層的に編成されたテキストドキュメントを作成、解析、操作するための言語に変えます。その豊富な機能セットには、テキスト構造化、プロジェクト管理、およびさまざまな形式にエクスポートできる公開システムが含まれています。ソースコードとデータはアクティブブロックに配置され、テキストセクションとは区別されます。「アクティブ」とは、コードブロックとデータブロックを評価してその内容または計算結果を返すことができることを意味します。コードブロック評価の結果は、文書内の名前付きデータブロックに書き込まれ、そこから別のコンピューティング言語で書かれた他のコードブロックで参照できます。このようにして、Org-mode バッファは、さまざまなコンピュータ言語が互いに通信する場所になります。Emacs と同様に、Org-mode は拡張可能です。新しい言語のサポートは、少数の Emacs Lisp 関数の定義を通じて、ユーザーがモジュール方式で追加できます。

(Schulte et al. 2012, 7)

Markdown は、拡張機能や外部ツールを通じてこの一部を模倣できますが、その場合、作成モデルは特定のパーサー、エディター、プラグインコレクションの偶然の交差点になります。Org-mode の機能は同じ 一貫したシステム に属しています。さらに重要なのは、それらはビルド後にのみ意味を持つ命令ではなく、エディター内でインタラクティブであることです。

Pandoc を境界として

魅力的なアプローチの1つは、blogatto に Org を直接解析する方法を教えることです。長期的にはこれを検討し、メインリポジトリにプッシュすることさえするつもりです。今のところ、pandoc はすでに Org を理解しており、GitHub Flavored Markdown を出力し、すでに引用処理機能を持っているため、変換ステージは退屈なままでいられます。

pandoc -s org/posts/example.org \
  -t gfm \
  --citeproc \
  --bibliography=priv/bibtex/emacs.bib \
  -o blog/posts/example/index.md

実際のコマンドは src/convert.gleam によって組み立てられます。これは、すべての Org ページと投稿を見つけ、priv/bibtex の下のすべての BibLaTeX データベースを追加し、Blogatto が期待するディレクトリ構造に Markdown を書き込みます。変換されたファイルはビルド成果物であり、Git によって無視されます。org/ ディレクトリが唯一の真実の情報源です。

汎用的な変換では十分でない場合のために、3つの小さな Lua フィルターがあります。

  • verse.lua は Org の verse ブロックを構造化された HTML として保持します。
  • bibliography.lua は生成された参照を正しくグループ化されたままにします。
  • images.lua は Org ドキュメントの隣で意味をなすファイルパスを、公開されるウェブサイトで意味をなすパスに変換します。

Gleam, Blogatto, および Lustre

コンバーターは通常の Gleam プログラムです。出力ディレクトリを作成し、すでに最新のファイルはスキップし、Pandoc を呼び出し、失敗を Result 値として報告します。変換が完了すると、Blogatto は生成された投稿を読み込み、それらのページと RSS フィードをビルドし、静的アセットを dist/ にコピーします。Lustre はサイトレイアウトで使用される HTML 要素を提供します。

意図的にこれ以上の説明はありません。Org-Publish を使用してこのほとんどを自動化することもできますが、html を生成する際に常に機能させるのが難しいいくつかの 品質向上 機能があります(シンタックスハイライトはそのうちの1つにすぎません)。

Nix による再現性

ここでは何も本当に変わっていません。Nix は依然としてすべてを機能させるためのダックテープです。nix develop に入ると、gleam、pandoc、make、その他のビルド時依存関係が提供されます。Devenv は、そのシェルを対話的に使いやすくしますが、同じ flake は、グローバルにインストールされているものに依存することなく、ビルド環境を再現します。

# ...
packages = {
  default = inputs'.nix-gleam.packages.buildGleamApplication {
    src = ./.;
    # `fs` (blogatto -> filespy の推移的依存関係) は
    # `pc` rebar3 プラグインを使用して NIF をビルドします。純粋なビルドが
    # hexpm にヒットしないようにバンドルします。
    rebar3Package = pkgs.rebar3WithPlugins {
      plugins = with pkgs.beamPackages; [ pc ];
    };
  };
};

# nix fmt + nix flake check (flakeModule によって自動配線)
treefmt = {
  projectRootFile = "flake.nix";
  programs.gleam.enable = true;
  programs.nixfmt.enable = true;
};

devenv.shells.default = {
  # ...
  packages =
    with pkgs;
    [
      gnumake
      pandoc
    ]
    ++ lib.optionals stdenv.isLinux [ inotify-tools ]
    ++ [ config.packages.default ];

  languages.gleam = {
    enable = true;
  };

  languages.lua = {
    enable = true;
    lsp.enable = true;
  };

  enterShell = ''
    echo "Starting Development Environment..."
  '';
};

# ...

開発環境内から、完全なビルドは意図的に平凡です。

make run
# または
make dev

結論

このウェブサイトは、単純な静的ページにしては(やや不条理な)数のツールを持っています。しかし、これらのツールのそれぞれは、狭いジョブを持っています。Org-mode はリッチなソースドキュメントを保持します。Pandoc はそれをポータブルな交換フォーマットに削減します。Blogatto はそのフォーマットをサイトに変換します。Gleam + Lustre は、すべての静的 HTML を生成する型チェックされたプロジェクトを提供します。Nix は再現可能な開発環境を提供します。

システムの中心は依然として Emacs です。執筆行為、ドキュメントの構造、そしてそれをサポートする計算をすべて1つの場所に保つという私の(頑固な)決定です。Org-mode は、思考中に操作できるドキュメントモデルであるため、その作業において Markdown よりも優れています。

参考文献

Garfinkle, Simson, Daniel Weise, and Steven Strassmann. 1994. UNIX-Hater Handbook. IDG Books Worldwide, Inc.

Knuth, Donald Ervin. 1984. “Literate Programming.” The Computer Journal 27 (2): 97–111.

Schulte, Eric, Dan Davison, Thomas Dye, and Carsten Dominik. 2012. “A Multi-Language Computing Environment for Literate Programming and Reproducible Research.” Journal of Statistical Software 46: 1–24.