typst-writer

Typst Writer

このスキルは、Typst を他の言語と混同することによるよくある構文エラーを避けることに重点を置き、正しい Typst コードを書くためのガイダンスを提供します。

基本原則

1. 他の言語の構文がそのまま当てはまると決して仮定しない - Typst には独自のセマンティクスがあり、特にデータ構造において顕著です
2. 不確かな構文は検証する - 確信が持てない場合は、公式ドキュメントを確認してください
3. 慣用的なパターンを使う - クリーンで保守しやすいコードのために Typst の慣習に従ってください

構文クイックリファレンス

重要な区別:

• 配列: (item1, item2) - 丸括弧
• 辞書: (key: value, key2: value2) - コロン付きの丸括弧
• コンテンツブロック: [markup content] - 角括弧
• タプルは存在しない - Typst には配列しかありません

詳細な構文ルールと一般的なパターンについては、references/syntax.md を参照してください。

ドキュメントリソース

公式ドキュメント

• コア言語リファレンス: https://typst.app/docs/reference/
• Typst Universe - パッケージとテンプレートの中央レジストリ:
  • メインページ（JS SPA）: https://typst.app/universe
  • レジストリ全体はただの通常の GitHub リポジトリです: https://github.com/typst/packages

Typst パッケージの検索

Typst Universe（公式のパッケージレジストリ）にはプログラムから利用できる API はありませんが、GitHub 経由でパッケージを検索できます:

• ほとんどのパッケージは GitHub でホストされています
• gh search または SearXNG のリポジトリ検索を使用してください（searxng-search スキルを参照）
• 例: リポジトリで「typst diagram」や「typst table」を検索する

GitHub CLI を使う場合

GitHub 直接検索の例:

# Search for typst repos about some topic
gh search repos --language "typst" --json "url,language,description" diagram arrows ... 

# List all files in a given repo
gh search code --repo "Jollywatt/typst-fletcher"

# In a repo, search through all files of some type
gh search code --repo "Jollywatt/typst-fletcher" --extension "md" arrow node ...

ドキュメントを参照すべきタイミング

• 関数のシグネチャやパラメータについて不確かな場合
• あまり一般的でない機能の構文を検証する必要がある場合
• 組み込み関数やメソッドを探している場合
• 利用可能なパッケージを調べている場合（例: 図表用の fletcher、マージンノート用の drafting、高度な表用の tablex）

必要に応じて WebFetch を使用して、検証のために最新のドキュメントを取得してください。

ワークフロー

1. 書く前に: 構文が不明確な場合は、references/syntax.md またはドキュメントを参照してください
2. 書いている間:
   • 適切なデータ構造の構文を使用してください（配列は ()、コンテンツは []）
   • 関数は #let name(params) = { ... } で定義してください
   • 状態にアクセスする場合は context ブロックを使用してください
3. 書いた後: Python や他の言語の構文が紛れ込んでいないか見直してください

避けるべきよくある間違い

• ❌ ものを「タプル」と呼ぶ（Typst には配列しかありません）
• ❌ 配列に [] を使う（代わりに () を使ってください）
• ❌ 配列の要素に arr[0] でアクセスする（代わりに arr.at(0) を使ってください）
• ❌ マークアップコンテキストでコードに # プレフィックスを付け忘れる
• ❌ コンテンツブロック [] とコードブロック {} を混同する

ワークフローの例

// Define custom functions for document elements
#let important(body) = {
  box(
    fill: red.lighten(80%),
    stroke: red + 1pt,
    inset: 8pt,
    body
  )
}

// Use state for counters
#let example-counter = state("examples", 1)

#let example(body) = context {
  let num = example-counter.get()
  important[Example #num: #body]
  example-counter.update(x => x + 1)
}

// Arrays for data
#let factions = (
  (name: "Merchants", color: blue),
  (name: "Artisans", color: green)
)

// Iterate and render
#for faction in factions [
  - #text(fill: faction.color, faction.name)
]

コーディングガイドライン

コンテンツとレイアウトを混在させない

#set、#show、およびカスタム関数を使用して、コンテンツとレイアウト指示を混在させることを避け、さらに重要なこととして、ドキュメント全体を通じて視覚的な一貫性を確保してください。

簡潔さを優先し、デフォルトに頼る

Typst の関数は、レイアウトパラメータに対して多くの場合まともなデフォルト値を持っています。パラメータにどの値を指定すべきか不確かな場合は、指定せずにおくだけで構いません。

同様に、多くの関数パラメータは、ユーザーがレイアウトをどの程度細かく制御したいかに応じて、異なる型を受け入れます。たとえば:

#table(
  columns: 3,
  ...
)

および

#table(
  columns: (auto, auto, auto),
  ...
)

はまったく同じことをします。列の 1 つのサイズをより細かく制御したくない場合は、最初のものを優先してください。

利用可能な場合はマークアップショートカットを使う

#emph[to-emphasize] の代わりに to-emphasize を使ってください。

式よりも Unicode リテラルを優先する

たとえば $pi$ や #sym.pi の代わりに単に π と書き、#emoji.abacus の代わりに単に 🧮 と書いてください。

Typst ファイルからの内容の読み取り

コンパイルだけでなく、typst CLI コマンドは typst query を使って Typst ファイルに対してクエリを実行できます。Typst セレクタを使用し、結果を JSON として取得できます。

たとえば、typst query the_document.typ "heading.where(level: 1)" | jq ".[].body.text" は、ドキュメント内に存在するすべてのレベル 1 のセクションタイトルを一覧表示します。残念ながら、ファイル内での正確な位置は教えてくれませんが、Typst ファイルは grep しやすいです。

詳細については、[https://typst.app/docs/reference/introspection/query/#command-line-queries](query に関するオンラインドキュメント) を参照してください。

パッケージの使用

特殊な機能が必要な場合:

1. https://typst.app/universe/ でパッケージを検索します
2. #import "@preview/package:version" でインポートします
3. パッケージのドキュメントで API を確認します

人気のパッケージ:

• drafting: 作業中のドキュメント向けの注釈/コメント
• gentle-clues: コールアウト、ヒント、ノート、警告
• showybox: 汎用的でカスタマイズ可能なテキストボックス。ヘッダーとフッター付き。たとえば定義、定理、重要な段落の強調表示に
• itemize: 項目リスト、列挙、チェックリスト、ツリーリストなどのための見栄えのよいレイアウト
• cetz: 汎用的な図/描画。明示的な配置 (座標) が可能 - ほとんどの Typst 描画ライブラリの基盤
• fletcher: グラフ、フローチャート、オートマトン、ツリーなど - 自動配置
• chronos: シーケンス図
• timeliney: ガントチャート
• herodot: 線形タイムライン
• lilaq: データ可視化とプロット
• tablem: Markdown ライクなテーブル形式でテーブルを記述 - 罫線、セルの結合などを簡単に制御
• cmarker: Markdown (インラインまたは別ファイルから) を Typst ドキュメントの一部としてレンダリング
• polylux: プレゼンテーション、スライド
• suiji: Typst コードでの乱数生成
• zebraw: 行番号、ハイライトされた行、インラインの Typst コメント/説明などを備えたコードリスト
• lovelace: アルゴリズム/擬似コード
• conchord: コード変更を重ねた歌詞、ギターのコード図とタブ
• eqalc: 数式を実際に呼び出し可能な Typst 関数に変換
• jlyfish: Julia ノートブックとしての Typst: Julia コードを Typst 内に埋め込んでコンテンツや可視化などを生成
• pyrunner: 非 I/O の Python コードを Typst 内に埋め込んで呼び出す

テンプレートの使用

Typst Universe では、レポート、論文、履歴書、プレゼンテーションなど向けの多くの既成テンプレートがホストされています。テンプレートは完全なドキュメントのスタイリングと構造を提供します。

テンプレートの検索

• テンプレートを閲覧: https://typst.app/universe/search/?kind=templates
• カテゴリで絞り込み: report、paper、thesis、cv など
• テンプレートのドキュメントでパラメータと例を確認する

テンプレートの使用

1. テンプレートをインポートします: #import "@preview/template-name:version": *
2. #show: template-name.with(param: value, ...) で適用します
3. テンプレートのドキュメントで必須パラメータと任意パラメータを確認します

例:

#import "@preview/bubble:0.2.2": bubble

// Some templates (like bubble) don't use the standard metadata set by `#set document(...)` (for now?),
// so we factor it out:
#let doc-md = (
  title: [My report],
  author: "Claude",
  date: datetime(year: 2025, month: 12, day: 8) // ALWAYS include explicit date in code (so we don't default to date of PDF build)
)

#set document(..doc-md)

#show: bubble.with(
  ..doc-md,
  date: doc-md.date.display("[day]-[month]-[year]"), // some templates want a string here, not a `datetime` object, so we override date here
  subtitle: "A detailed analysis",
  affiliation: "Your Organization",
  main-color: rgb("#FF6B35"),
  color-words: ("important", "key", "critical"),
)

// Your content follows
= Introduction
...

パッケージとの主な違い:

• テンプレートは通常、単一の「メイン」関数を介して #show: を使ってドキュメント全体にスタイリングを適用します
• パッケージは明示的に呼び出す関数/コンポーネントを提供します
• テンプレートは多くの場合、タイトルページとドキュメント構造が組み込まれています

人気のテンプレート: charged-ieee (IEEE 論文)、bubble (カラフルなレポート)、modern-cv (履歴書)

参考文献と引用

Typst は BibTeX (.bib) または Hayagriva (.yml) 形式のファイルを使用した引用と参考文献をサポートしています。

references/bibliography.md を参照してください。

参考文献ファイルには、可能な限り必ず適切な URL を含めてください。

参考文献が関連する箇所にはどこでも、必ず @ref-name の引用を本文に含めてください。適切に引用されなければ、よい参考文献も役に立ちません。

完全なドキュメント構造のパターン

これは学術論文の例を示しています。 書く必要があるほとんどのレポートはそこまで正式である必要はありませんが、これは一種の典型的な例です。

「手動」レイアウト (必要な場合、たとえばユーザーが特定のレイアウト要件を指定した場合)

#set document(
  title: "Document Title",
  author: "Your Name",
  date: auto,
)

#set page(
  paper: "a4",
  margin: (x: 2.5cm, y: 2.5cm),
  numbering: "1",
)

#set text(size: 11pt)
#set par(justify: true)
#set heading(numbering: "1.")

// Title page
#align(center)[
  #text(size: 24pt, weight: "bold")[Document Title]

  #v(1cm)
  #text(size: 14pt)[Your Name]

  #v(0.5cm)
  #datetime.today().display()
]

#pagebreak()

// Table of contents
#outline(title: "Table of Contents", indent: auto)

#pagebreak()

// Main content
= Introduction
Your introduction text...

= Methods
...

= Results
...

= Conclusion
...

#pagebreak()

// Bibliography
#bibliography("refs.bib", title: "References", style: "ieee")

テンプレートの使用 (より簡単)

#import "@preview/charged-ieee:0.1.4": *

#show: ieee.with(
  title: "Your Paper Title",
  authors: (
    (name: "Author One", email: "[email protected]"),
    (name: "Author Two", email: "[email protected]"),
  ),
  abstract: [
    Your abstract text here...
  ],
  index-terms: ("keyword1", "keyword2", "keyword3"),
  bibliography: bibliography("refs.bib"), // the ieee template takes care of bibliography itself. That's not always the case
)

// Content starts immediately
= Introduction
Your introduction text...

= Methods
...

= Results
...

= Conclusion
...

トラブルシューティング

フォントが見つからないという警告

「unknown font family」という警告が表示される場合は、フォント指定を削除してシステムのデフォルトを使用してください

Note: フォントの警告はコンパイルを妨げません。ドキュメントはフォールバックフォントを使用します

テンプレート/パッケージが見つからない

「package not found」でインポートが失敗する場合:

• Typst Universe で正確なパッケージ名とバージョンを確認してください
• @preview/package:version 構文のタイプミスを確認してください
• ネットワーク接続を確認してください（パッケージは初回使用時にダウンロードされます）
• 覚えておいてください: Typst は特定のバージョンを含む完全修飾インポートを使用します - 更新すべきパッケージキャッシュはありません

コンパイルエラー

よくある修正方法:

• 「expected content, found ...」: マークアップが期待される場所でコードを使用しています - #{ } で囲むか、適切な構文を使用してください
• 「expected expression, found ...」: マークアップコンテキストで # プレフィックスが欠落しています
• 「unknown variable」: スペルを確認し、インポートが正しいことを確かめてください
• 配列/辞書のエラー: 構文を見直してください - どちらも () を使用し、辞書には key: value が必要で、単一要素の配列は (elem,) です

パフォーマンスの問題

大きなドキュメントの場合:

• #include "file.typ" を使用して複数のファイルに分割してください
• 特定のページをコンパイル: typst compile doc.typ output.pdf --pages 1-5
• コンパイルのプロファイリング（実験的）: typst compile --timings doc.typ