typst-author

typst-author スキル

概要

このスキルは、エージェントが Typst ドキュメントを生成、編集し、内容を検討するのに役立ちます。クイックスタートの例、詳細なワークフロー、Typst の完全なドキュメント（ガイド、チュートリアル、リファレンス）へのリンクを提供します。

最小限のドキュメント例

#set document(title: "My Document", author: "Author Name")
#set page(numbering: "1")
#set text(lang: "en")

// Enable paragraph justification and character-level justification
#set par(
  justify: true,
  justification-limits: (
    tracking: (min: -0.012em, max: 0.012em),
    spacing: (min: 75%, max: 120%),
  )
)

#title[My Document]

= Heading 1

This is a paragraph in Typst.

== Heading 2

#lorem(50)

ワークフロー

• 新しい Typst プロジェクトの作成：「最小限のドキュメント例」を出発点として使用します。チュートリアルに目を通して基本を確認し（docs/tutorial/writing-in-typst.md）、.typ ファイルを作成します。.typ ファイルを編集するたびに、typstyle が利用可能な場合は、以下の編集後のフォーマットチェックを行います。
• 既存コンテンツの編集：対象のテキストを見つけて変更を適用し、必要に応じてリファレンスで構文を確認します（docs/reference/）。.typ ファイルを変更するたびに、以下の編集後のフォーマットチェックを行います。
• フォーマットとスタイル設定：スタイルガイド（docs/reference/styling.md）を参照して、set rule、show rule、カスタムテーマを確認します。

ドキュメント

• 構文と基礎：docs/reference/syntax.md
• スタイル設定と show/set ルール：docs/reference/styling.md
• スクリプトとランタイムの動作：docs/reference/scripting.md
• ページ設定とテーブル：docs/guides/page-setup.md と docs/guides/tables.md
• タスク別の執筆支援：docs/tutorial/writing-in-typst.md、docs/guides/*.md、docs/reference/**/*.md

詳細な手順

1. 最優先：ローカルドキュメントを信頼します。Typst に関する内部の学習データは古くなっていたり、誤った内容が含まれていたりする可能性があります。コードを生成する前に、必ずローカルの docs/ フォルダーで関数名、パラメーター、構文を確認してください。
2. ローカルのファイル検索ツールと開くツールを使い、上記のパスにある関連ドキュメントを読みます。
3. 構文やリファレンスに関する質問にはローカルドキュメントを使用します。同梱ドキュメントで構文、関数名、パラメーター、リファレンスの動作を確認してください。ドキュメントを確認してもランタイムまたは評価の動作が不明な場合に限り、最小限の Typst プローブを実行します。
4. ユーザーの依頼に従って、.typ ソースを生成または変更します。
5. この作業で作成または編集したすべての .typ ファイルに対し、以下の編集後のフォーマットチェックを実行します。
6. .typ ファイルを作成または編集した場合、またはユーザーが明示的に検証を求めた場合は、フォーマットの判断が完了した後に typst compile で検証します（ツールにアクセスできる場合）。
7. 変更したファイルと結果を要約します。完全な .typ の内容を提示するのは、ユーザーが求めた場合、または直接編集できない場合に限ります。必要に応じて、レンダリング済みのプレビュー（PDF/HTML）も提示できます。

不確かな動作のプローブ

• 同梱ドキュメントでランタイムまたは評価の動作が明らかにならない場合は、プローブを使用します。
• docs/reference/scripting.md に記載されている Typst スクリプトを使って、対象のケースをモデル化します。
• プローブが必要な場合は、一時的な .typ ファイルを作成するのではなく、標準入力を使ったファイル不要のプローブを優先します。metadata(...) <probe> で値を出力し、typst query - "<probe>" --field value --one で読み取ります。docs/reference/introspection/query.md と docs/reference/introspection/metadata.md を参照してください。
• 例：printf '#metadata(1 + 2) <probe>\n' | typst query - "<probe>" --field value --one

編集後のフォーマットチェック

1. command -v typstyle を使って typstyle が利用可能か確認します。利用できない場合は、残りのフォーマットチェックをスキップしてください。
2. .typ ファイルを変更するたびに、直前に作成または編集したファイルに対して typstyle --check <file> を実行します。
3. typstyle --check が失敗した場合は、対応を決める前に typstyle --diff <file> でフォーマッターによる変更を確認します。
4. フォーマッターによる変更が、新規作成したファイルまたは今回のタスクで作成・編集したコードに限られる場合にのみ、typstyle -i <file> でフォーマットを適用します。
5. フォーマットによって既存の未変更コードが変わる場合は、作業を止めてユーザーに確認してください。差分が自分の編集箇所の範囲外に及ぶ場合、またはフォーマッターによる変更がすべて自分の編集箇所に限られると確信を持って確認できない場合は、適用せずに確認してください。

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

重要な違い

• 配列：(item1, item2)（丸括弧）。docs/reference/foundations/array.md を参照してください。
• 辞書：(key: value, key2: value2)（コロンを含む丸括弧）。docs/reference/foundations/dictionary.md を参照してください。
• コンテンツブロック：[markup content]（角括弧）。docs/reference/foundations/content.md を参照してください。
• タプルはありません：Typst には配列しかありません。

ハッシュの使い方（マークアップとコード）

• マークアップまたはコンテンツブロック内でコード式を開始するには # を使います。これによりコードとテキストを区別できます。コンテンツを生成する関数の呼び出しや、マークアップ内でのフィールドアクセスには必須です：#figure[...]、#image("file.png")、text(...)[#numbering(...)]。
• コードコンテキスト（引数リスト、コードブロック、show ルールの本体）では # を使わないでください。例：#figure(image("file.png"))（image の前に # は付けません）。
• 参考：docs/reference/scripting.md、docs/tutorial/writing-in-typst.md

// Incorrect (missing # inside content block)
text(...)[(numbering(...))]

// Correct
text(...)[(#numbering(...))]

スタイルルール：set と show

• set：要素関数の省略可能なパラメーターを設定するルールです（現在のブロックまたはファイル内に適用されるスタイルの既定値）。
• show：選択した要素を対象にし、set ルールを適用するか、要素の出力を変換・置換するルールです。
• 一般的なスタイル設定には set を使い、選択的または構造的な変更（例：heading.where(level: 1)、ラベル、テキスト、正規表現）には show を使います。

// Set rule: configure optional parameters for an element type
#set heading(numbering: "I.")
#set text(font: "New Computer Modern")

// Show-set rule: apply a set rule only to selected elements
#show heading: set text(navy)

// Show transform rule: replace/reshape element output
#show heading: it => block[#emph(it.body)]

よくある間違いを避ける

• 「タプル」と呼ぶこと（Typst には配列しかありません）。
• 配列に [] を使うこと（代わりに () を使います）。
• arr[0] で配列の要素にアクセスすること（arr.at(0) を使います）。
• マークアップ／コンテンツブロックで # を省略すること（例：text(...)[numbering(...)] は text(...)[#numbering(...)] とする必要があります）。
• コードコンテキストで # を使うこと（例：引数リスト内の figure(#image("x.png"))）。
• コンテンツブロック [] とコードブロック {} を混同すること。
• インポートした変数や関数にアクセスする際、名前空間を含め忘れること（例：hsl だけでなく color.hsl を使います）。
• LaTeX 構文を使うこと（\begin{...}、\section、その他の LaTeX コマンドは使わないでください）。
• 存在しない環境を作り上げること（例：tabular は存在しません。table を使います）。

高度な機能

• カスタムテーマ：テーマの作成については docs/reference/styling.md を参照してください。
• スクリプト：自動生成には Typst のスクリプト機能（docs/reference/scripting.md）を使います。
• 数式と可視化：数式や図については docs/reference/math/ と docs/reference/visualize/ を参照してください。

大規模プロジェクトの場合

大規模なプロジェクトでは、複数のファイルに分けて整理することを検討してください。

• #include "file.typ" を使って複数のファイルに分割します
• 関連ドキュメント：docs/reference/foundations/module.md

トラブルシューティング

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

「unknown font family」という警告が表示された場合は、フォント指定を削除してシステムのデフォルトを使用してください。注：フォントに関する警告はコンパイルを妨げません。ドキュメントでは代替フォントが使用されます。

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

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

• Typst Universe でパッケージ名とバージョンが正確か確認してください。
• @preview/package:version の構文に誤字がないか確認してください。

コンパイルエラー

よくある解決方法：

• 「expected content, found ...」：マークアップが必要な箇所でコードを使用しています。#{ } で囲むか、正しい構文を使用してください。
• 「expected expression, found ...」：マークアップ／コンテンツブロックに #（または #(...)）がありません。
• 「unknown variable」：スペルを確認し、インポートが正しいことを確かめてください。
• 配列／辞書のエラー：構文を見直してください。両方に () を使用します。辞書では key: value が必要です。要素が1つの配列は (elem,) とします。