ハクソク

世界を動かす技術を、日本語で。

Quarkdown: モダンなMarkdownベースの組版システム

356日前原文(github.com)

概要

Quarkdownは 多機能なMarkdown拡張 による組版システム。 書籍・スライド等への多様な出力 が可能。 スクリプト機能 や関数定義をMarkdownで実現。 高速コンパイル とライブプレビュー対応。 多様なターゲット・比較・導入方法 も明確。

Quarkdownとは

  • Quarkdown は、 Markdownベース の最新組版システム。
  • 柔軟性 を重視し、 書籍やインタラクティブなプレゼンテーション を簡単に作成可能。
  • Turing完全な拡張Markdown で、強力な自動組版を実現。
  • CommonMarkやGFM の拡張として誕生し、 関数や追加構文 を導入。
  • 標準ライブラリ により、レイアウト、I/O、数式、条件分岐、ループもサポート。
  • 独自関数や変数の定義、ライブラリ作成も可能。
    • 例: .function {greet} to from: **Hello, .to** from .from!
  • スクリプト対応 で、従来Markdownでは困難な動的コンテンツも実現。
  • ライブプレビュー や 高速コンパイル に対応。

主なターゲットと出力形式

  • HTML: 標準対応
  • プレーン出力: デフォルト
  • スライド: reveal.js連携
  • ページ組版（書籍・記事）: paged.js連携
    • ページ組版にはWebサーバーが必要（-pオプション）
  • PDF: HTMLサポート機能すべて対応
    • 詳細はWikiのPDFエクスポートページ参照
  • 出力形式の指定: .doctype {slides}や.doctype {paged}関数で制御

他システムとの比較

  • Markdown, LaTeX, Typst, AsciiDoc, MDX との比較
    • 簡潔さ・可読性: Markdown/Typst/AsciiDoc/MDX/Quarkdownは◎、LaTeXは×
    • ドキュメント制御: Quarkdown/LaTeX/Typstは◎
    • スクリプト対応: Quarkdown/Typst/MDXは◎
    • 書籍・記事出力: Quarkdown/LaTeX/Typst/AsciiDocは◎
    • サードパーティプレゼン対応: Quarkdown/LaTeX/Typst/AsciiDocは◎
    • 学習コスト: Quarkdown/Markdown/AsciiDoc/MDXは低め
    • ターゲット: QuarkdownはHTML/PDF両対応

構文例

  • Quarkdown構文 例
    • .tableofcontents 目次生成
    • # Section セクション
    • 1. **First** item 番号付きリスト
    • .center 中央寄せ
    • .row alignment:{spacebetween} 画像横並び配置
  • LaTeXとの比較 も容易

導入方法

  • 最新版のquarkdown.zip をダウンロードし、解凍
  • binディレクトリ に実行ファイル
  • PATH登録 でコマンド利用が容易
  • lib/qmdディレクトリ にライブラリ格納
  • Java 17以上 が必須
  • 主要OSすべて対応

プロジェクト作成

  • quarkdown create [ディレクトリ]でプロジェクトウィザード起動
    • メタデータ・初期コンテンツが自動生成
  • Wikiで詳細参照可能
  • 手動で.qmdファイル作成 も可能

コンパイル方法

  • quarkdown c file.qmdでコンパイル、出力ファイル生成
  • 複数ファイル構成 の場合はルートファイルを指定
  • 他ファイルのインクルード も可能
  • REPLモード （quarkdown repl）で対話的に試行

主なオプション

  • -p, --preview: コンパイル後自動リロード、Webサーバー起動
  • -w, --watch: ファイル変更時自動再コンパイル
  • --pdf: PDF出力
  • -o <dir>, --output <dir>: 出力ディレクトリ指定
  • -l <dir>, --libs <dir>: 外部ライブラリディレクトリ指定
  • -r <renderer>, --render <renderer>: レンダラー指定（html/html-pdf等）
  • --server-port <port>: Webサーバーポート指定（デフォルト8089）
  • --pretty: 出力コードを整形（デバッグ向け）
  • --clean: 出力ディレクトリ初期化（破壊的操作）
  • --strict: エラー時即終了（通常は文書内にエラー表示）
  • --no-media-storage: メディアストレージ無効化
  • -Dloglevel=<level>: ログレベル設定

モックドキュメント

  • Mock はQuarkdownで書かれた 視覚要素集
  • mockディレクトリ にソース、quarkdown c mock/main.qmd -pでコンパイル
  • 全テーマ組み合わせのPDF も生成・公開

コントリビューション

  • 貢献歓迎
  • CONTRIBUTING.md参照で IssueやPull Request による貢献方法を確認

スポンサー

  • プロジェクト支援者へ特別感謝

コンセプト

  • ロゴ はMarkdownアイコンをベースに、 Quarkdownの多機能性とカスタマイズ性 を象徴
  • 回転する矢印 で進化・拡張性を表現
  • 惑星に見えるが実はダウンクォーク （down quark）をモチーフ
  • ダウンクォーク は物質の基本構成要素であり、Quarkdownの 根本思想 を体現

Hackerたちの意見

これと最近注目されているTypstを比較してみるのも面白そうだね。機能比較のマトリックスに全然載ってないのはちょっと驚き。

└

最後にチェックした時、TypstはHTMLを出力できなかったよ。

これはQuarto [0]とどう違うの？名前も似てるし、拡張子も同じ、目的も似てるみたいだけど、今のところ機能は少なめだね。[0] https://quarto.org/

└

名前の似てるのは別のところから来てるんだろうね。今回はQuarkXPressを思い出させるかも。収束進化だね！ :D

└

Quartoは、広く成功したR Markdownエコシステムの精神的な後継者だってことを忘れないでね。同じ開発者によるものだよ。https://quarto.org/docs/faq/#who-are-the-developers-of-quart...

比較からTypstが抜けてるね。

└

これはスタンドアロンなの？つまり、実際に人が使えるファイルフォーマットってこと？彼らのウェブサイトを見る限り、サービスを使わないと動かないみたいだけど、自分でホスティングしないといけないのかな？

これはMarkdownの上に乗っかるレイヤーとして好きだな。ただ、Markdownの主な使い方はコンテンツだけで、レイアウトやロジックについては意見がないのがいいところなんだよね。ウェブ用にはCSSやJSを使ったり、印刷用にはインタープリターやテーマを使って追加できるし。

これやTypstとかは主に論文のための組版システムだよね。HTMLとかの代替があればいいけど、Typstも試したけど、作者たちは論文や長文の組版にしか本気で興味がないみたい。フォームや請求書、チラシ、配布資料、リーフレット、名刺みたいなのは、せいぜい後回しって感じ。追記：実はTypstじゃなくてSileのことを考えてたけど、Typstにも同じことが言えると思う。Typstは商業的だったからあまり深く調べなかったけど。

└

もう知ってるかもしれないけど、paged.jsはどう？ [0]: https://github.com/pagedjs/pagedjs

└

オンラインエディタは商用だよ。でも、TypstをApache 2.0ライセンスで無料で公開しているGitHubリポジトリもある。私はcargo（Rust）を使ってインストールしたし、オンラインエディタは使ってない。

└

あなたが言ったことにTypstを使えない理由ってあるの？ 使えない理由が思いつかないんだけど（インタラクティブフォームを除いてね、これはすでに取り組まれてるみたいだし[1]）。pdf-writerの低レベルバックエンドはフォームフィールドのサポートを実装してるみたいだから、Typstに実装されるのも時間の問題だと思うよ。[1] https://github.com/typst/typst/issues/1765

└

Typstはローカルで使えるし、商用部分を回避できるよ。いろんな種類のドキュメントを作るのがすごく簡単なんだ。私はスライドや配布資料を作るのに使ってるけど、代替品よりもずっと使いやすいと感じてる。

└

Typstの最初の「本当の」使い道はポスター作成だったよ[0]。LaTeXでやるよりずっと簡単だった。図を囲んだり、ボックス間でテキストを流したりする機能が欠けてるけど、TeXもそれはないし、両方ともTypstで計画されてるみたい。 [0]: https://dvdkon.ggu.cz/projects/pppql/poster.pdf

面白いけど、これにはTypstにはない何があるんだろう？

.function {greet} .greet {world} from:{iamgio} greetの呼び出しには少し違った構文（例えば、2つのドット）を使うことを強く勧めるよ。そうしないと、システムが新しいキーワードを導入する際に、既存のドキュメントの関数名と衝突するリスクがあるから。

└

もっとキーワードが必要なのかな？ この構文はちょっとSmalltalkの構文を思い出させるけど、Smalltalkは有名なことにたった6つのキーワードでやりくりしてたよ。quarkdownの構文を詳しくチェックしてないし、Smalltalkほど考え抜かれてるとは思わないけど、少ないキーワードでやりくりするのは十分可能だと思う。問題は、今のところ彼らのコンセプトがどれだけ完成されてるかだね。それに、特定のバージョンのQuarkdown用にドキュメントをラベル付けするバージョニングメカニズムがあるかもしれない。

└

後方互換性のあるデザインは、まずユーザー定義関数に解決して、次に組み込みキーワードにするべきだね。そうすれば、新しいキーワードが後方互換性のない変更にならないから。

ちょっと関連があるけど、フォームについて: https://forms.md

└

彼らの構文が「マークダウン風」ってどういうことか全然理解できない。見えるのは、コードに囲まれた何か宣言的な言語だけだよ。

マークダウン、クアーダウン、Typst、これやあれ。これってLaTeXに似てるよね。全部がすごく混乱してて、標準化されてないから、HTML+CSSに戻っちゃった。

└

ああ、そうそう、CSSとHTMLでメモを書くのが好きなんだ。最高だよ！でも本気で言うと、新しい流行が出てきた時に、それを使わなきゃいけないわけじゃないし、わざわざ時間をかけて見る必要もないよね。マークダウンは、その派生物が消え去った後も残ってると思う。

└

Emacsをエディタとして使うのが気にならなければ、成熟していて信頼性のあるOrg-modeもあるよ。

└

同じく。ウェブ開発でDOMを使って要素を置き換えるのは、WebSocketと一緒にやると意外と楽しいよね。300個のクソ重いフレームワークや97種類の文法を覚えるのはもう飽きた。HTML、CSS、JavaScript。AIにマークダウンからHTMLに変換するツールを作ってもらえば、すぐに使えるのに。

└

基本的なマークダウンは、サクッと作業するのにめっちゃ便利だよね。でも、問題は人々がシステムの上にシステムを作り始めることだと思う。本来はもっと複雑なケースには使うべきじゃないのに。まあ、別に気にしないけど、誰かが「ただそれだけ」のために作ったものを、理解せずに使って上に乗っけていくのを見ると、初期のアイデアやシステムの限界や範囲を理解せずにやってるなって思う。「あれ、機能が足りない」って言うけど、「いや、それはそういう風に作られてないから」って感じ。Windowsのメモ帳がいくつかのフォーマット機能を持ってるのを見たけど、それを改善だとは思わない。メモ帳はメモ帳としての目的があったんだから。

すごく興味深いね。僕は自分の履歴書をLaTeXとマークダウンの組み合わせで書いてるんだ。Pandocを使ってファイルをLaTeXに変換して、それをPDFにしてる。この方法はフロントエンドではもっと整理されてるかもしれないけど、今の流れが好きなんだ。ツールが成熟してるから、数年後に履歴書を見返しても、ちゃんとコンパイルできるし。