メインコンテンツまでスキップ

引用

Citation（引用）コンポーネントは、Bibliography（文献リスト）という中央のコレクションに保存された資料を引用します。各資料は一度だけ登録され、それを引用するすべてのトピックは引用キーを通じてその資料を参照します。出版社名や発行日を修正すると、その資料へのすべての引用がドキュメントセット全体で更新されます。

文献データはCitation Style Language（CSL）規格に従っており、これはZoteroやMendeleyなどの文献管理ソフトが書き出すのと同じ形式です。インポート機能はまだないため、それらのソフトから資料を移すには、CSL-JSONをRaw CSL-JSON overrideに貼り付けます。

文献リストを管理する​

資料は、それを引用するトピックとは別に、専用の1つのコレクションに保存されます。

  1. コレクション一覧から Bibliography（文献リスト）を選択します。
  2. リストに参考文献を追加します。
  3. Citation key（引用キー）を設定します。トピックはこのキーを使って資料を参照するため、短く、変更しない値にします。例：smith2020。
  4. Type（種別）を選択します。その種別に関係するフィールドだけが表示されるので、雑誌記事の場合はISSNが、書籍の場合はISBNが表示されます。
  5. 残りのフィールドを入力して保存します。
注記

引用キーを変更すると、それを使っているすべての引用が壊れます。トピックがそのキーを引用したら、キーは変更しないものとして扱ってください。

存在しないキーを指す引用は、用語集の項目や変数がそうするのと同じように、その場でその旨を表示します。

typo-here NOT FOUND

ビルド自体は成功し、そのページの他の引用にも影響しないため、キーの入力ミス1つでサイト全体のプレビューが止まることはありません。ビルドはそうした引用も一覧にまとめて表示するので、見ていなかったページのミスにも気づけます。

フォームに表示されないフィールド​

このフォームは、ドキュメント用の資料に必要なフィールドだけを扱い、規格が定義するすべてのフィールドを扱うわけではありません。次の2種類のフィールドは意図的に除外されています。

  • 引用番号や、同じ著者が同じ年に発表した複数の著作を区別する文字など、フォーマッター自身が算出する値。
  • Type（種別）の一覧にない資料タイプに属するフィールド。

フォームで表現できない資料には、Raw CSL-JSON override を使います。ここに有効な内容を入力すると、上記のフィールドの代わりに使われますが、引用キーはそのまま保持されます。

資料を引用する​

  1. Embed（埋め込み）リストから Citation（引用）を選択します。
  2. 引用に資料を追加します。
  3. 引用キーの一覧から Source（資料）を選択します。
  4. 必要に応じて、資料の特定の箇所を示す Locator（参照位置）と Locator type（参照位置の種類）を指定します。

参照位置は14や14-16のように、飾りのない値として入力します。「p.」などは付けないでください。それは引用スタイル自身が付加するもので、スタイルによって付け方の流儀が異なります。

1つの引用で複数の資料を引用できます。2つの引用を並べて置くのではなく、1つの引用に複数の項目を追加してください。そうすることで、引用スタイルがそれらをまとめて表示できます。

例​

次の引用は、単一の資料を参照します。

<Cite items={[{ key: "smith2020" }]} />

これは特定のページを参照します。

<Cite items={[{ key: "smith2020", locator: "14", label: "page" }]} />

これは2つの資料を、それぞれのページ参照とともにまとめて引用します。

<Cite items={[
  { key: "smith2020", locator: "14", label: "page" },
  { key: "jones2019", locator: "3-5", label: "page" }
]} />
注記

同じ資料を2回引用しても、最初の引用が再利用されるわけではありません。それぞれが独自の位置を持ち、後続の引用をどう短縮するかはスタイルが決めます。

変更がいつ反映されるか​

Bibliography（文献リスト）コレクションで資料を編集すると、その資料へのすべての引用がすぐに更新されます。出版社名を修正すれば、再起動なしに、見ている目の前でページに変更が反映されます。

次の3つは動作が異なるため、それぞれの違いを知っておくと役に立ちます。

変更内容反映されるタイミング
資料を編集するすぐに
トピックに引用を追加する次回のビルド時
引用スタイルを変更するCMSを再起動した後

新しく追加した引用は、次のビルドが行われるまで何も表示しません。プレースホルダーもエラーも表示しません。まだフォーマット済みのテキストがないためで、中途半端にフォーマットされた引用を表示するくらいなら、何も表示しない方がましだからです。

引用スタイルは、再起動が必要な唯一の設定です。これは、引用を本文中に置くか脚注に置くかを決めるためで、単なる文言ではなくページの構造そのものを変えるので、ページを再ビルドする必要があります。

注記

引用はトピックでは機能しますが、ブログ記事では機能しません。脚注はどちらでも機能します。ブログ記事に置かれた引用は何も出力しません。

スタイルを選ぶ​

引用スタイルは、引用と参考文献リストの書式を制御します。スタイル同士の違いは見た目だけでなく実質的なものです。あるスタイルは上付きの番号を本文に置き、資料を注釈に置きます。別のスタイルは著者名と発行年を括弧に入れて本文中にそのまま置きます。

スタイルはトピックごとではなく、サイト全体で一度だけ設定します。1つのドキュメントセットの中でスタイルを混在させるのはスタイル上の誤りです。読者は、あるマーカーが何を意味するのか判別できなくなってしまいます。

コレクション一覧から Settings（設定）を選択し、Citations（引用）を開いて、Citation style（引用スタイル）を選びます。

スタイル引用の位置参照例
Chicago (author-date)本文中Smith, Jane. 2020. The Art of Documentation. Oxford University Press.
Chicago (notes and bibliography)脚注内Smith, Jane. The Art of Documentation. Oxford University Press, 2020.
Harvard (Cite Them Right)本文中Smith, J. (2020) The Art of Documentation. Oxford: Oxford University Press.
IEEE本文中、番号付き[1] J. Smith, The Art of Documentation. Oxford: Oxford University Press, 2020.
Oxford (Guide to Style, notes)脚注内Smith, J., The Art of Documentation (Oxford, 2020).

英語のバリエーション​

どの英語で書かれているかを明示しているのはOxfordスタイルだけです。他のスタイルはそれをサイト側に委ね、既定ではアメリカ英語になります。そのため、日を先に置く日付形式を想定するスタイル（Cite Them Rightなど）であっても、特に指定しない限り資料の日付はAugust 18, 2026のように表示されます。

これを修正するには、English variant（英語のバリエーション）をGlobal Englishに設定します。これは英語ページの日付の順序、引用符、綴りにのみ影響します。他の言語は、それぞれのロケールの慣習に従います。

言語を追加する​

docStaticに標準で含まれる5つの言語は、そのまま利用できます。別の言語を追加するには、1つのファイルだけが必要です。それは、その言語の引用符、日付の順序、「アクセス日」のような用語を提供するCSLロケールです。

このファイルがなくても、新しい言語のページはビルドされますが、その引用は英語のまま表示されます。ビルドはその旨を知らせ、追加すべきファイル名を示します。

! No CSL locale for "it": its citations will use the style's default (English).
  Add csl/locales/locales-it-IT.xml to fix.

CSLロケールプロジェクトからそのファイルを取得し、csl/locales/に配置してください。それ以外は何も必要ありません。言語は名前によって自動的に対応するロケールに結び付けられます。

新しい言語のタイトルはReferences page title（参照ページのタイトル）でも設定してください。設定しない場合、資料一覧ページの見出しは英語のままになります。

注釈形式の引用スタイルでの引用​

Chicago (notes and bibliography) や Oxford のもとでは、引用は脚注でもあります。すでに書かれている <Cite> は、そのまま番号付きの注釈になります。トピック側で何かを変更する必要はありません。

引用と、あなた自身が書いた脚注は、ページに登場する順に1つの共通した番号の並びを共有します。OxfordもChicagoも、注釈は「文書全体を通して連続して」番号を振るため、読者は2つの並びを区別できません。

番号付けはサイトのビルド時に計算されるため、繰り返し引用される資料をそのスタイルが正しく短縮でき、毎回全文を繰り返す必要がありません。

1つの注釈にコメントと引用を両方含める​

Chicagoスタイルでは、1つの注釈に資料と自分自身のコメントの両方を含めることが認められています。脚注の中に引用を置くと、新たに2つ目の注釈を作るのではなく、その注釈の中に引用が現れます。

<Footnote summary="1"><Cite items={[{ key: "jones2019" }]} /> これは反対の立場を主張しています。</Footnote>

引用を先に、コメントをその後に置いてください。注釈形式のスタイルは引用をピリオドで終えるため、引用を挟むようにコメントを書くと、後に続けて書く場合に比べて不自然に見えます。

数語程度の短いコメントであれば、代わりに引用のSuffix（接尾辞）フィールドを使ってください。これはどのスタイルでも引用にそのまま付随し、本文中に引用を置くスタイルでも同様です。

例

再利用は無料ではありません[1]。ツールがどれほど便利さを約束しても同じです[2]。

注釈形式のスタイルでは、上記の2つのマーカーはいずれも注釈であり、このページの他のすべての注釈と同じ並びで番号が振られます。最初の注釈は資料とコメントを一緒に含み、2つ目の注釈は引用だけを含みます。本文中に引用を置くスタイルでは、2つ目の引用は文の中にそのまま現れ、脚注だけに番号が振られます。

実際の例​

次の段落は実際に動作するものです。その引用は、Bibliography（文献リスト）コレクションの資料をもとに、このサイトが現在設定しているスタイルで表示されます。

例

ドキュメントは一度書いて再利用するのが最善です[3]。この考え方はツールよりも古くからあります[4]。同じ資料は後でもう一度取り上げられます[5]。誰もがこれに賛成しているわけではありません[6]。2つの資料は1つの引用の中でまとめて引用できます[7]。

Settings（設定）で選んだスタイルによって、注目すべき点が変わります。

  • Oxford、あるいはChicago (notes and bibliography) のような注釈形式のスタイルでは、上記のマーカーはすべて脚注であり、注釈そのものはこのページの末尾にあります。著者自身の注釈と引用は1つの並びとして続きます。The Art of Documentation への2回目の引用が短縮されているのは、最初の引用との間に別の注釈が入ったためです。
  • Harvard、IEEE、Chicago (author-date) のような本文形式のスタイルでは、引用は文の中にそのまま現れ、番号が振られるのはこの段落の2つの脚注だけです。

その段落の元のソースは、どちらの場合でも変わりません。

Documentation is best written once and reused<Cite items={[{ key: "smith2020", locator: "14", label: "page" }]} />.
The idea predates the tooling<Footnote summary="...">Technical writers were reusing content...</Footnote>,
and the same source returns to it later<Cite items={[{ key: "smith2020", locator: "22", label: "page" }]} />.
Not everyone agrees<Footnote summary="..."><Cite items={[{ key: "jones2019" }]} /> This argues that reuse...</Footnote>.
Two sources can be cited together in one citation<Cite items={[{ key: "smith2020" }, { key: "csl-spec" }]} />.

資料一覧ページ​

生成されたページには、選択したスタイルで整形された資料の一覧が表示されます。これはトピック内の引用とは別のものです。資料の注釈形式・本文形式での表現と、参考文献リストでの表現は、意図的に異なる形になっています。

このページを公開するには、コレクション一覧から Settings（設定）を選択し、Citations（引用）を開いて、Generate a sources page（資料一覧ページを生成する）を有効にします。

文献リストか参考文献か​

List every source, including uncited ones（未引用のものも含めすべての資料を掲載する）は、このページに何を掲載し、どのようなタイトルにするかを決めます。

設定掲載内容既定のタイトル
オンBibliography（文献リスト）コレクションのすべての資料参考文献
オフトピックが実際に引用している資料のみ引用文献

この2つの名称は入れ替え可能なものではありません。「参考文献」には、引用していない著作――関連する読み物や補足資料――を含めてかまいません。「引用文献」は慣例として、本文が実際に引用しているものだけを収録するため、そこに載っている項目は、ドキュメントのどこかで実際に引用として登場するはずだと期待できます。

ここでの「引用されている」とは、言語を問わず、ドキュメントセット全体のどこかで引用されていることを意味します。まだ翻訳されていないページでしか引用されていない資料であっても、各言語の一覧に表示され続けます。そのため、翻訳が遅れている言語でも一覧が縮小することはありません。

ページに名前を付ける​

References page title（参照ページのタイトル）は、見出しと目次でのラベルを言語ごとに1つずつ設定し、上記の既定タイトルを上書きします。言語を追加してタイトルを設定してください。タイトルを設定しない言語は、既定のタイトルのままになります。

ページを配置する​

このページは/docs/referencesとして公開されますが、目次には自動的に追加されません。どこに配置するのが適切かは、あなただけが知っています。

  1. コレクション一覧から Table of Contents（目次）を選択します。
  2. docs/references.mdxを指すドキュメント項目を、好きな場所に追加します。

後でこのページを無効にした場合でも、その項目はそのまま残しておいてかまいません。ページが存在しない項目は、ビルドを失敗させるのではなく無視されるだけです。

注記

このページはビルドのたびに、サイトの各言語ごとに文献リストから再構築されるため、内容が古くなることはありません。手動で編集しないでください。変更は上書きされてしまいます。修正する場合は、Bibliography（文献リスト）コレクション側の資料を直してください。

注記

この設定を変更すると、ページの名前が変わり、サイドバーでのラベルも変わりますが、アドレスは変わりません。引き続き/docs/referencesのままです。

Footnotes

  1. Alex Jones, 「Single-sourcing in technical communication」, Journal of Documentation Practice, 42/3 (2019年), 112–34, https://doi.org/10.0000/jdp.2019.42.3.112. これは、コストが節約分を上回るという立場を主張しています。 ↩
  2. Citation Style Language Project, 「Citation Style Language Specification」 (2024年), https://docs.citationstyles.org/, 参照 2026年8月18日. ↩
  3. Jane Smith, The Art of Documentation (Oxford, 2020年), 14. ↩
  4. テクニカルライターは、シングルソーシングという名前が付く前から、条件付きテキストによってコンテンツを再利用していました。 ↩
  5. Smith, The Art of Documentation, 22. ↩
  6. Jones, 「Single-sourcing in technical communication」. これは、再利用は節約分よりもコストがかかるという立場を主張しています。 ↩
  7. Smith, The Art of Documentation; Citation Style Language Project, 「Citation Style Language Specification」. ↩