mdBook - Markdownで本を作るコマンドラインツール

 (rust-lang.github.io)
4 ポイント 投稿者 GN⁺ 2023-07-01 | 1件のコメント | WhatsAppで共有
  • ドキュメントやチュートリアルを本の形で配布したいとき、mdBook 0.5.3 は Markdown ベースの執筆と、ナビゲーションしやすい出力をあわせて提供する
  • 軽量な Markdown 構文 と統合検索により、執筆者は書式よりもコンテンツに集中できる
  • コードブロックの シンタックスハイライト とテーマファイルにより、技術文書に必要な読みやすさや出力形式の調整が可能
  • プリプロセッサ とバックエンドは、カスタム構文、コンテンツ修正、複数の出力形式のレンダリングのための拡張ポイントを提供する
  • Rust プロジェクトや The Rust Programming Language の書籍で使われているツールであり、Rust ドキュメントのエコシステムとのつながりが大きい

Markdown の書籍制作に必要な基本機能

  • mdBook は Markdown で本を作るためのコマンドラインツール
  • 製品ドキュメント、API ドキュメント、チュートリアル、講義資料のような、整然としていてナビゲーションしやすいコンテンツ制作に適している
  • 執筆体験と読書体験を支える機能をあわせて提供する
    • 軽量な Markdown 構文でコンテンツ作成に集中できる
    • 書籍内での統合 検索 をサポート
    • 複数言語のコードブロックにカラーの シンタックスハイライト を適用
    • テーマ ファイルで出力形式をカスタマイズ可能

拡張性と Rust エコシステムとの接続

実際の利用事例と貢献方法

  • mdBook のドキュメント自体が、mdBook で生成された成果物の実例
  • Rust プログラミング言語プロジェクトが mdBook を使用しており、The Rust Programming Language の書籍も利用事例のひとつ
  • mdBook は 無料のオープンソース プロジェクト
  • mdBook のソースとドキュメントは Mozilla Public License v2.0 で配布される

関連記事

1件のコメント

 
GN⁺ 2023-07-01
Hacker Newsのコメント

  • このプラットフォームは、ライブラリをバンドルしたりベンダリングしたりせず、CDNでホスティングされたライブラリを使っていると記憶している。そのためユーザーは、CDN障害だけでなく、そのサーバーが収集するデータにもさらされる
    さらに残念なのは、フロントエンドで Highlight.js と MathJax を使う方式が非常に無駄なこと。すべてのクライアントが構文と LaTeX を直接パース・レンダリングしなければならず、同じ結果を得るために訪問のたびに同じ作業を繰り返すことになる。構文ハイライトはビルド時に処理できるし、JavaScript が必要になる理由もほとんどない

    • MathJax は CDN でホスティングされているようで、CSS と他の JS ファイルは HTML ファイルの横に一緒に置かれている
      MathJax サポートがオプションなので、そのような選択になったのだと思う: https://rust-lang.github.io/mdBook/format/mathjax.html
      ただし MathJax の JS が再び CDN の追加ファイルを読み込む可能性が高く、なぜ MathJax ファイル一式を生成された HTML の横に置かないのか理解しづらい
    • これに関連する未マージの PR がすでにあるようだ: https://github.com/rust-lang/mdBook/pull/1918

  • このスレッドで挙がっていたドキュメント・静的サイトツールとしては、Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook あたり
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • nimibook も使ったことがある
      mdBook を Nim に移植したものだが、Nim の JavaScript バックエンドを使って インタラクティブコンテンツを生成する機能も拡張されている。自分ではまだ使っていないが、必要なときにインタラクティブ要素を一か所で作れるという発想は気に入っている: https://pietroppeter.github.io/nimib/interactivity.html
    • Sphinx も外しにくい。ワークフローがブログ、フォーラム、スレッド形式よりも 書籍形式により適している
    • HackMD は数式表記をサポートしており、共有・共同編集できる Markdown ドキュメントを作るときによく選ぶ: https://hackmd.io/
    • こうしたツールの機能比較表や比較サイトがあるとよい。組み込み検索、PDF 出力、ePub 出力、複数テーマ、そのほかの機能を比較してみたい
    • https://jupyterbook.org/en/stable/ もある。Jupyter Book に貢献している

  • MdBook、Jekyll、MkDocsを使ってみたが、MdBookは基本プロジェクトには洗練されている一方で、あまりにミニマルすぎると感じた。気に入ったMdBookサイトのソースを見ると、カスタムRustコードで拡張されている場合があった
    おすすめとしては、MkDocsは合理的に柔軟な標準の選択肢、Jekyllはランディングページやブログのようにより多くの柔軟性が必要な場合、Antoraは複数のプロジェクトや複数バージョンのドキュメントを集約して最高のドキュメントサイトを作りたく、そのために多くの労力をかける意思があるときに向いている。AsciiDocにはドキュメント作成に役立つ機能が多い
    HugoはJekyllのように柔軟に見えるが、思いどおりに合わせるまでにより多くの手間が必要で、テーマごとの動作の違いも大きすぎるように思う。使っていたテーマに必要な機能がなく、別のテーマに変えようとしたが移行は簡単ではなく、結局あきらめた。MdBookはかなり活発に見えるので、最終的には追いつきそうだ

    • 長年のJekyllユーザーで、ブログ用としては今でも素晴らしいと思うが、ドキュメントサイト向けの静的サイトジェネレーターの中では Docusaurus が最も良かった: https://docusaurus.io/
      JavaScriptベースのツールを使いたくなくて長く先延ばしにしていたが、使ってみると始めやすく非常に高速で、標準のサイトも美しく、カスタマイズもしやすい。MDXサポートも優れている
    • material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) のランディングページは本当に洗練されている。専用ソフトウェア向けのテーマだと考えると特に印象的だ
    • 科学や統計の分野では Quarto が優れていると思う: https://quarto.org
    • Antoraは初めて聞いたが、複数のリポジトリからドキュメントを組み立て、ブランチでバージョン管理する方式はまさに求めていた動作だ。ただ、既存ドキュメントがMarkdownとインタラクティブなReactコンポーネントの組み合わせなので、MDXを使わない点 は惜しい
    • MkDocsをよく使っていて、とても気に入っている
      BookStackも試しているところだが、よりWikiに近いものの、技術に詳しくない人には良い。通常のMkDocsプロジェクトはVSCodeで編集してGitリポジトリに置くが、BookStackはすべてWebベースだ

  • 以前は til.secretGeek.net の生成にGitBookを使っていたが、時がたつにつれて遅くなり、サイトのビルドに45分かかるようになったうえ、使っていた機能が廃止されたり「premium」になったりした。結局、エンシティフィケーション が始まったということだ
    あまりに良さそうな無料ツールを使っているなら、数年待てば壊れる可能性が高い。結局、.NETでごく最小限の静的サイトジェネレーターを自作して、再び数秒でビルドできるようにした。他人に使えと宣伝はしていないが、人気が出たら自分も結局同じように壊してしまいそうだからだ

  • 複数のプロジェクトで mdBook を使ってきたが、最近は material for mkdocs のほうが標準機能がはるかに多く、使いやすいと感じる
    たとえば右側のページ目次が気に入っているが、mdBook にはこの機能がはっきりと欠けている。mdBook では SUMMARY を非常に細かく構成し、もともと1ページに置けた内容を複数ファイルに分割するやり方が標準のように見える

    • material for mkdocs は、Pythonのインストールや仮想環境の設定を受け入れるだけの価値がある
    • MkDocsはかなり長く気に入っている。最小限の煩わしさで作業を終えられ、選べるテーマも多く、自分でカスタマイズしたり新しく作ったりするのも比較的簡単だ
    • 章ごとの 目次 を得るために https://github.com/JorelAli/mdBook-pagetoc を使っている

  • 数日前、小さなプロジェクトのドキュメント化のために mdBook を使い始めたが、必要なものに正確に合った 小さな静的ページジェネレーター だ
    HUGOも使ってみたが、mdBookに比べると大きすぎて重厚すぎるように感じる。今はObsidian/VIMでドキュメントを編集し、Giteaにプッシュすると1分以内に公開ドキュメントが生成される

    • Hugoに book theme(https://github.com/alex-shpak/hugo-book) を組み合わせて使っている。Hugoに慣れていなければ適応に時間が必要だが、その後はHugoが提供するshortcodeなどの柔軟性が良く感じられる
      適切な shortcode によって図や数式などの自動番号付けができる。mdBook でも自動番号付けができるのか気になる。右側の目次やタグ、ページを列に分ける機能もあり、KaTeXサポートも良い。mdBook は MathJax を使っているようで、デプロイは push や rsync だけで簡単だ
    • 最近 PlantUML拡張 を使い始めたが、ドキュメントにアーキテクチャ図を入れるのに役立っている

  • 最近、コンテンツを .md から .mdx へ少しずつ移しながら見直し始めたのだが、かなり新鮮だった。Markdown でいちばんつらかったのは、使う方言ごとに限界が異なり、その限界を拡張するやり方もそれぞれバラバラなことだった
    標準的な GitBook Markdown 方言の 80〜90% にはとても満足しているが、ときどき複雑な表や、数行だけを強調しつつ構文ハイライトを維持するコードブロック、インタラクティブなスライダー、文書内に埋め込まれた計算機、特定のグラフやチャートが必要になる。大きなチームで MDX がどう機能するかは分からないが、個人作業には確実に改善に見える

    • .mdx を初めて知って [0] を見てみた。フロントエンドの標準化の流れを十分追えていなかったようだ
      方言がなくなって 1 つの汎用的なアプローチが生まれればいいのだが、ドキュメントには「MDX は React に縛られず、Preact、Vue、Emotion、Theme UI などでも使え、classic/automatic JSX ランタイムの両方をサポートする」とある。Svelte 実装 [1] もすでにあるので、今回はフロントエンドフレームワークに縛られた方言がさらに増えるパンドラの箱ではないのか、よく分からない。.mdx の内部でも分かれうるし、.md とも互換性がないかもしれない
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • 完全に同意する。Mdsvex を見つけたときは人生が変わるような感覚だった: https://mdsvex.com
    • .mdx は https://astro.build/ ととても簡単に使える。Astro は JavaScript メタフレームワークでありつつ、クライアントに JS を送らない 静的サイト生成優先アプローチ を取っている
      使えるテーマもあるが、現代の Web 開発者なら自作するのもかなり簡単だろう

  • Markdown ベースの本を作るために、無料のオープンソースなクロスプラットフォームツール KeenWrite を作った: https://github.com/DaveJarvis/keenwrite
    KeenWrite は文書組版のために ConTeXt を呼び出し、プレビューモードでは数式組版に KeenType フォークを使う。コマンドラインから PDF を生成できる。今書いている本では、外部ファイルで定義した複数の変数を本文から参照し、メタデータとして PDF の属性を渡し、chapters 引数で一部の章だけをビルドできる。theme ディレクトリには色、フォント、レイアウト、注釈などの組版指示が入っている
    サンプル出力: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • なぜ Markdown やそれに近い形式が、本や文書、ほとんどすべての文章の基本形式ではないのか気になる。数年前に Typora へ移ってから、自分で書く文章には Word/Writer がほとんど不要になり、他人が送ってきた文書を開くときだけ使うようになった
    読んでいる本の 90% も、Markdown 形式であってはいけない明確な理由があるようには見えない。紙の本をきれいに印刷するには組版が必要なのは理解できるが、コンピューターやスマートフォンで読む、あるいは MS/LibreOffice からそのまま印刷する大半のテキストは、どうせそうした組版作業がきちんと行われていない

    • Markdown は 保存形式 としてはかなり貧弱だ。準公式標準の CommonMark はあるが機能不足なので、たいていは GitHub Markdown のような別方式が使われ、個々のアプリが互換性のない形で Markdown を拡張していることも多い
      AsciiDoc のようなより良い代替もあるが、文書化に特化していて、Markdown に近い勢いはない。Markdown が比較的遅れて登場した形式であることを考えると、なぜ本が Markdown であるべきなのか、というほうがより妥当な問いだ。バイナリや XML ベースの形式に比べた Markdown 最大の利点は、プレーンテキストとしてある程度読めることだが、ほとんどの出版社や読者にとってそれはそれほど重要ではない
    • 書籍の組版には、訓練を受けていない目には見えにくい 多くの繊細さと複雑さ があり、Markdown+CSS だけではそれを扱うには十分に精密ではない。HTML/CSS+JS も技術的には可能だが、デジタル組版の最先端水準には大きく遅れている
      これは典型的な「自分ならもっと上手くできる」というエンジニアの罠でもあるので、調査なしにそう仮定すべきではない。組版はここで扱っているツール群よりはるかに古い分野であり、その間に蓄積された価値ある知見や技術を、Markdown がいくつかの用途にはほぼ十分だからという理由で捨てるべきではない
    • 仕事で文書をたくさん書くが、Markdown とレンダリング結果を並べて見る方式が好きだ。構文に慣れると、Word のようなエディタより Markdown のほうがずっと速く、テキストエディタでリストを 1 つ書くだけでも煩わしく感じる

  • mdBook は使いやすく、特にユーザーが テーマを選べる点 が気に入っている。主に電子書籍のオンライン版 [0] とキュレーションした資料 [1][2] に使っている
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/