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/1-writing.md)、.typ ファイルを作成します。
  • .typ ファイルを編集するたびに、typstyle が利用可能な場合は、以下の編集後のフォーマットチェックを実施します。
• 既存のコンテンツの編集：
  • 対象のテキストを見つけて変更を適用します。必要に応じて、リファレンスに照らして構文を確認します (docs/reference/index.md)。
  • .typ ファイルを変更するたびに、以下の編集後のフォーマットチェックを実施します。
• フォーマットとスタイル：
  • set rule、show rule、セレクター、変換については、スタイルガイドを参照します (docs/reference/language/styling.md)。
  • 視覚的な一貫性を保ちます。新しいレイアウト、図、表、描画では、特に指示がない限り、ドキュメントで既に使用されているフォント、色、タイポグラフィの階層を再利用する必要があります。内部の一貫性も維持してください（同じ機能には同じサイズと色を使用します）。

ドキュメント

• 概要：全体像については docs/overview.md、リファレンスの構成については docs/reference/index.md、チュートリアルの進行順については docs/tutorial/index.md を参照してください。
• チュートリアル：基本的なマークアップ、関数、ラベル、引用、数式については docs/tutorial/1-writing.md、セットルール、ページ設定、見出し、テキストの書式設定については docs/tutorial/2-formatting.md、テンプレート、showルール、より複雑なスタイリングについては docs/tutorial/3-advanced.md、再利用可能なテンプレートとパッケージについては docs/tutorial/4-template.md を参照してください。
• 言語構文：マークアップ／数式／コードの各モード、コメント、エスケープ、識別子については docs/reference/language/syntax.md を参照してください。
• 言語スクリプト：式、コードブロック／コンテンツブロック、バインディング、条件分岐、ループ、フィールド、メソッド、モジュール、パッケージ、演算子については docs/reference/language/scripting.md を参照してください。
• 言語スタイリング：セットルール、showルール、セレクター、変換については docs/reference/language/styling.md を参照してください。
• 言語コンテキスト：スタイルコンテキスト、位置コンテキスト、ネストされたコンテキスト、コンパイラーの反復処理については docs/reference/language/context.md を参照してください。
• 基礎：基本的な型と関数、std、sys.version、sys.inputs については docs/reference/library/foundations.md を参照してください。
• ドキュメントモデル：見出し、図、参考文献一覧、引用、参照、番号付け、アウトライン、リスト、表、ドキュメント構造については docs/reference/library/model.md を参照してください。
• レイアウト：ページ、ブロック、ボックス、グリッド、段組み、配置、間隔、変換、測定など、ページ上の要素の配置については docs/reference/library/layout.md を参照してください。
• テキスト：テキストのスタイリングと text 関数については docs/reference/library/text.md を参照してください。
• 数式：数式の構文、記号、数式、配置、フォント、アクセシビリティ、数式関数については docs/reference/library/math.md を参照してください。
• 描画とメディア：図形、画像／グラフィックスのプリミティブ、色、グラデーション、線、視覚的なアクセシビリティについては docs/reference/library/visualize.md を参照してください。
• イントロスペクション：カウンター、状態、位置、query、ドキュメントを考慮した生成コンテンツについては docs/reference/library/introspection.md を参照してください。
• データの読み込み：CSV、JSON、TOML、YAML、XML、CBOR、rawファイルなどの外部データの読み込みとエンコードについては docs/reference/library/data-loading.md を参照してください。
• 記号と絵文字：名前付き記号と省略形については docs/reference/library/sym.md、絵文字については docs/reference/library/emoji.md を参照してください。
• エクスポート形式：PDF標準とPDF固有の機能については docs/reference/export/pdf.md、HTMLエクスポートと型付きHTMLについては docs/reference/export/html.md、複数出力のバンドルとアセットについては docs/reference/export/bundle.md、画像のエクスポートについては docs/reference/export/svg.md と docs/reference/export/png.md を参照してください。
• ガイド：ページ、余白、ヘッダー、フッター、番号付け、段組みについては docs/guides/page-setup.md、セマンティックな表と表のスタイリングについては docs/guides/tables.md、セマンティック構造、代替テキスト、言語、PDFアクセシビリティ、エクスポート時の考慮事項については docs/guides/accessibility.md、LaTeXからTypstへの変換については docs/guides/for-latex-users.md を参照してください。

詳細な手順

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

不確かな挙動の検証

• 同梱ドキュメントで実行時または評価時の挙動が明らかにならない場合は、プローブを使用してください。
• docs/reference/language/scripting.md の説明に従って、Typst スクリプトで対象の状況をモデル化してください。
• プローブが必要な場合は、一時的な .typ ファイルを作成する代わりに、typst eval を使ったファイル不要の式プローブを優先してください。システム値については docs/reference/library/foundations.md、文脈に応じたドキュメントクエリについては docs/reference/library/introspection.md を参照してください。
• 例：typst eval '1 + 2'

編集後の書式チェック

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/library/foundations.md を参照してください。
• 辞書：(key: value, key2: value2)（コロンを含む丸括弧）。docs/reference/library/foundations.md を参照してください。
• コンテンツブロック：[markup content]（角括弧）。docs/reference/language/scripting.md を参照してください。
• タプルはありません：Typst にあるのは配列だけです。

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

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

高度な機能

• スタイルの再利用：set ルール、show ルール、コードブロックやコンテンツブロックのスコープ内でのスタイル設定については、docs/reference/language/styling.md を参照してください。
• スクリプト：自動生成には Typst のスクリプト機能（docs/reference/language/scripting.md）を使用します。
• 数式とビジュアライゼーション：数式と図については、docs/reference/library/math.md および docs/reference/library/visualize.md を参照してください。

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

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

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

トラブルシューティング

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

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

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

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

• Typst Universe でパッケージ名とバージョンが正確か確認します。
• @preview/package:version 構文に誤字がないか確認します。パッケージのインポート構文については docs/reference/language/scripting.md を、Typst Universe の例については docs/guides/for-latex-users.md を参照してください。

コンパイルエラー

よくある対処方法：

• 「expected content, found ...」：マークアップが必要な場所でコードを使用しています。#{ } で囲むか、適切な構文を使用します。
• 「expected expression, found ...」：マークアップ／コンテンツブロック内の #（または #(...)）が不足しています。
• 「unknown variable」：スペルを確認し、インポートが正しいことを確かめます。
• 配列／辞書のエラー：構文を見直します。どちらにも () を使用し、辞書では key: value の形式を使います。要素が 1 つの配列は (elem,) です。