paper

Quarkdownでqdファイルをpdfに変換します。

仕様

• 初回実行時はpdfブランチが自動で作成されます。(qdファイルが一つもなかった場合エラーで終了しブランチは作成されません。)
• theme等を変更し全てビルドしなおしたい時はpdfブランチ削除してmasterを変更すれば全てビルドしなおします。
• 初回実行時qdファイルは再帰的に検索され全て変換されます。
• 元々のファイルと同一のフォルダ構造で配置します。
• pdfブランチにはpdfファイルのみを生成します。
• masterからqdファイルを削除するとpdfからも自動で削除されます。
• 変更があったファイルのみをビルドするようにしています。
• リネームおよび移動した場合は旧ファイル名のpdfは残ります。
• _で始まるファイル(_setup.qdなど)は単体では変換されません。.includeで読み込む共通設定や分割用のファイルはこの名前にしてください。
• テーマ・用紙・フォントなどの共通設定は_setup.qdにまとめてあります。文書の先頭で.include {_setup.qd}と書いて読み込んでください。(including other files)
  • _setup.qdからの相対パスではなく、その文書から見た相対パスです。サブフォルダに置いた文書なら.include {../_setup.qd}になります。
  • .includeの後に同じ関数を呼べばその文書だけ設定を上書きできます。
• 変換対象は.qdのみです。mdから移行する場合はmd-to-qd.shを参照してください。
• --strictを付けているので、未定義の関数呼び出しなど変換時のエラーがあればビルドを停止します。
• ビルドは公式Actionquarkdown-labs/setup-quarkdownでQuarkdown本体(JRE・PuppeteerとChromeを含む)を入れて実行します。バージョンは2系の最新リリースを自動で選びます。
  • インストール先($RUNNER_TOOL_CACHE/quarkdown)をactions/cacheでキャッシュしているので、バージョンが変わらない限り2回目以降のセットアップはダウンロード無しで済みます。
  • GitHub Actionsのubuntuランナーではpuppeteerが用意するChromeのsandboxがAppArmorで弾かれるため、CIでは--pdf-no-sandboxを付けています。手元で変換する場合は不要です。
• PDFはHTMLをヘッドレスChromeで描画したものなのでLaTeXは不要です。
• 文書の設定はファイル先頭の関数呼び出しで書きます。主な記法はsample.qdに一通り並べてあるので、そちらとwikiを参照。
  • 種別: .doctype {paged} (document types)
  • 用紙: .pageformat size:{A4} margin:{2cm} (page format)
  • テーマ: .theme {paperwhite} layout:{latex} (themes)
  • フォント: .font {GoogleFonts:BIZ UDPMincho} (font configuration)
• 日本語フォントはQuarkdownに同梱されていないため、Google Fontsかリポジトリ内のフォントファイルを指定します。既定では_setup.qdで本文にBIZ UDPMincho、コードにM PLUS 1 Codeを指定しています。
  • コード用のフォントを別に指定しないと、インラインコードやコードブロック内の日本語が豆腐(□)になります。テーマ既定の等幅フォントに日本語が無いためです。
  • Mermaidの図は本文と別のフォントで描画されるため、図の中の日本語は表示されません。ラベルは英数字で書いてください。(図のキャプションは本文扱いなので日本語で書けます)
• その他機能追加,質問はissueでお願いします。

プレビュー

Quarkdown本体のライブプレビューを使います。JRE同梱なのでJavaは不要です。(Node.jsが無ければ自動で入ります)

curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env "PATH=$PATH" bash

WSLで使う場合はWindows側ではなくWSL内にインストールします。他のインストール方法(Homebrew, Scoop等)は本家のREADMEを参照。

quarkdown c sample.qd -w -p --allow global-read

-wが保存のたびに再コンパイル、-pがwebserver(既定でlocalhost:8089)を立ててブラウザを開き自動リロードします。.doctype {paged}はpaged.jsを使うのでwebserver越しでないと正しく表示されません。(CLI options)

• --allow global-readはリポジトリ外・親ディレクトリのファイル(サブフォルダ文書からの../_setup.qdなど)を読むために付けています。
• ブラウザを開かずポートだけ使いたい場合は-b none、ポート変更は--server-portです。
• PDFを手元で出したい場合はquarkdown c sample.qd --pdf --strict --allow global-readです。出力先はquarkdown-output/(.gitignore済み)なので、リポジトリを汚さずに確認できます。

VS Codeの公式拡張Quarkdown(Ctrl+Shift+Vでプレビュー、Ctrl+Alt+PでPDF出力)も使えます。設定に以下を入れると.includeや画像の読み込みで権限エラーになりません。

{
  "quarkdown.additionalCompilerOptions": "--allow global-read"
}

Quarkdown not found. Please install Quarkdown first.と出る場合はインストールが済んでいないかPATHが通っていません。設定quarkdown.pathに実行ファイルのパス(既定はquarkdown、install.shなら/usr/local/bin/quarkdown)を指定してください。VS CodeはWSLに接続した状態で使います。

使い方

Use this templateをクリックして新規リポジトリを作成してそこに.qdファイルを追加していきます。

mdからの移行

既にmdで書いている場合はmd-to-qd.shを一度実行すると全てqdに移行できます。(引数にファイルを渡すとそれだけ変換します)

./md-to-qd.sh

• 先頭のYAMLフロントマターを取り除きます。(そのままだと---が区切り線、title:行が見出しとして本文に出てしまいます)
• その文書から見た相対パスで.include {_setup.qd}を先頭に足します。既に書いてある場合は足しません。
• _で始まるファイルは分割用とみなして.includeを足しません。
• 元のmdは削除するので、結果を確認してからコミットしてください。README.mdは対象外です。

Quarkdown自体はMarkdownの上位互換なので、本文の書き方はほとんどそのままで通ります。ただし数式はQuarkdownの記法($ x $のように前後に空白)のみ対応で、\begin{equation}やスペース無しの$x$はそのまま文字として出ます。