ユーザーガイド4:Fragment を投稿する

$ 公開 2026-11-11 | | 更新 2026-11-14
コンテキスト: Fragments の有効化と Markdown の作成・編集から、ホームのプレビュー、ページ分割と共有、多言語、任意の Giscus コメントまで。

Markdown で短い考え、画像、コードを記録して安定したリンクで共有し、必要ならコメントを有効にします。


出力
語 2.2k トークン 2.8k

入門ガイドの第4 / 8回です。全ガイドの順序 · 設定リファレンス。

一言の考え、1枚の画像、短いコードのために、完全な記事を書く必要はありません。Fragments はそれらを時系列の独立一覧にまとめ、ホームから最新内容をプレビューできます。

現在の統合版 starter 向けの記事です。既存プロジェクトにコマンドや機能がない場合、インストールと個人情報の設定にある更新手順を済ませてから進めてください。

1. Fragments 一覧を有効にする

src/site.config.ts を開き、次の fragments を既存の theme に統合します。すでに theme があれば中の項目を追加・編集し、同名オブジェクトを重複作成しないでください。

theme: {
  fragments: {
    enabled: true,
    pageSize: 20,
    comments: { enabled: false },
  },
},
項目 既定値と実際の役割
theme.fragments.enabled 既定 false。有効な言語の一覧を生成し、内容のあるホームにプレビュー入口を表示できます。
theme.fragments.pageSize 既定 20。1ページの件数を1–100の整数で指定し、ブログの記事数とは独立しています。
theme.fragments.comments.enabled 既定 false。コメントのポップアップを有効にし、後述する Giscus リポジトリ設定も必要です。

npm run dev で起動し、ターミナルの URL 配下の /<locale>/fragments/(例:/en/fragments/、/zh/fragments/)を開きます。対象言語が有効であることが前提です。内容がなくても空一覧を表示し、ページファイルを先に作る必要はありません。無効時は一覧もホーム入口も生成しませんが、Markdown は削除しません。

2. 既定の手順で Fragment を作る

プロジェクトルートで実行します。

npm run new-fragment

--locales と ANGLEFEINT_LOCALES が未指定なら、有効な全言語に同じ Fragment のひな形を生成し、初期状態は9ファイルです。保存先は src/content/fragments/<locale>/ で、同じ実行のファイルは ID と公開日時を共有しますが、自動翻訳は行いません。ターミナルに実際のパスが表示されます。ファイル名は UTC 日付とランダム ID を含む 2026-11-13-q8Lm3XzP.md などです。実際に生成されたファイルを開き、例のファイル名を手作業で作る必要はありません。

簡体中国語のみなら npm run new-fragment -- --locales zh、複数言語なら --locales en,zh を使えます。これらは代替手順なので1つを選び、全部実行する必要はありません。対象言語の自動有効化も行いません。公開前に未完成の他言語ひな形を内容ディレクトリから移してください。

コマンドを1回実行するたびに新しい Fragment を作成します。 続きを書くときは元ファイルを編集し、同じ内容のために作成コマンドを再実行しないでください。slug の指定は不要で、既存ファイルも上書きしません。

現在の starter には new-fragment スクリプトがあります。旧プロジェクトにない場合はテーマの更新を確認して、プロジェクト内の CLI を使います。

npx @anglefeint/astro-theme new-fragment

これは先ほどの作成コマンドの別表記です。「同じ」Fragment を作るために両方実行しないでください。

3. 仮の本文を置き換え、ID は残す

先頭は frontmatter で、2本目の --- の後が本文です。生成済みの id と pubDate を保ち、仮本文を自分の考えに置き換えます。次は形式の例であり、自分の ID を例の ID で上書きしないでください。

---
id: 'q8Lm3XzP'
pubDate: '2026-11-13T09:00:00+08:00'
---

長く悩んでいた問題が今日解決したので、小さな進歩を記録します。

現在対応する frontmatter は3項目です。

項目 指定方法
id 必須。大小文字を区別する英数字8文字ちょうどです。コマンドが生成して既存 ID と照合するため、自分で考える必要はありません。
pubDate 必須。解析可能な公開日時。生成された ISO 時刻を残すか、時刻・タイムゾーン付きの値を推奨します。
title 任意の文字列。一覧カードの見出しに表示し、省略しても投稿できます。

タイトルが必要なら同じ frontmatter に title: '小さな進歩' を追加します。記事の description やカバー用の heroImage は必要なく、画像は本文に記入します。

一覧は pubDate の新しい順、同時刻なら ID 順で、ファイル名順ではありません。UTC 表示のため、指定したローカル時刻と異なる場合があります。本文やファイル名の変更だけではコメント・共有の識別は変わりません。日時を変えると並び順とページ位置が変わります。

公開後は ID を保持してください。 同一言語の ID 重複はエラーで、異なる Fragment に同じ ID を使わないでください。旧 UUID や長い ID は現形式に合いません。元内容をバックアップしてから互換性を処理してください。旧 ID・共有リンク・コメントの自動移行はありません。一括 ID 変更を通常のファイル整理として行わないでください。

収集対象は src/content/fragments/ の .md のみで、.mdx は使えません。下書き・未来日フィルターもないため、draft: true や未来の日時では隠せず、未公開の内容はこのディレクトリの外へ置きます。

4. 画像、コード、数式を追加する

通常の Markdown の段落、リンク、リスト、引用を使えます。画像の例です。

![今回の進歩のスクリーンショット](/images/fragments/progress.png)

実画像を先に public/images/fragments/progress.png に置いてください。Fragment の隣に photo.png を置き、![画像の説明](./photo.png) でも参照できます。その他の記法、サイズ、コミット対象は記事と Fragments に画像を追加するを参照してください。

コードは Markdown のフェンスとインデントを保ちます。

```js
const progress = {
  done: true,
};
```

コードブロックは表示用であり、JavaScript を書いても実行しません。記事のコピーボタンや画像拡大が Fragment にもあるとは限りません。現在の Fragments 一覧には、その2つの記事向けインタラクションを組み込んでいません。

全体で数学が有効なら、Fragment も $x_1$ のインライン数式と2行の $$ の間の独立数式に対応します。ビルド時に描画し、誤った数式はコンパイル・ビルドを失敗させます。theme.math.enabled を無効にすると数学処理を止めます。記法は最初の記事を書くを参照してください。

ローカル dev または doctor が対応する Fragment 画像のレスポンシブ画像を準備します。Markdown、原画像、src/assets/blog/covers/ 全体をコミットしてください。通常の build と doctor は CI でも、正しい原画像から必要な派生画像を自動で補完・修復します。正しい既存資源は再利用し、原画像の欠落や不正なパスはエラーです。本文だけをコミットして画像を漏らさないでください。

5. ホームのプレビューと一覧のページ分割

Fragments が有効で現在の言語に内容があれば、ホームの header 下にピクセルアバターの入口を表示します。開くと最新3件までプレビューできます。別のホーム設定は不要で、記事数の homeLatestCount とは独立しています。

プレビューは文面、最初の有効画像、最初のコードの抜粋を含められますが、本文全体ではありません。画像とコードは高さを制限して切り取り、複数の画像やコードを全部表示しません。カード全体から対応 Fragment へ、下部の「プレビュー件数 / 現在の言語の総件数 →」から全一覧へ移動します。2件なら 2 / 2 で、固定3件ではありません。空一覧にはホーム入口を表示しません。

全一覧は theme.fragments.pageSize で分割します。簡体中国語の例では最初が /zh/fragments/、2ページ目が /zh/fragments/2/ です。外観・ページジャンプは共通の theme.pagination を使い、ブログの blogPageSize は Fragment の件数を決めません。

一覧で言語を切り替えると対象言語の1ページ目に移動し、同じ訳文やページ番号を維持する保証はありません。訳文の件数は異なってもよく、総数は言語ごとに数えます。

6. Fragment を共有する

Fragment は一覧内に表示し、各項目の独立した詳細ページは生成しません。共有にはカードの日付リンクか隣のコピーリンクボタンを使います。例:

https://your-domain.example/zh/fragments/#q8Lm3XzP

ドメインと ID を実際の値に置き換えます。日付リンクとコピーは一覧のルートに ID を付け、現在のページ位置に依存しません。追加、日付変更、pageSize 変更後に再ビルド・再配備すると位置索引も更新します。

対象が現在のページにない場合、JavaScript が現在の言語の静的索引を必要時に読み、対象ページへ移動して位置を合わせます。JavaScript がなくてもページ一覧は読めますが、ページ横断の自動移動とコピーボタンは使えません。クリップボード権限がなければ選択可能な URL を表示して手動コピーできます。

/2/ を含むアドレスバーの URL を長期共有に使わないでください。旧ページが残っていれば古いアンカーを補正できますが、ページ番号自体が消えた場合は通常の404になり、位置移動スクリプトは404を処理しません。削除済み ID や索引の読込失敗は案内を表示しますが、削除した内容は復元しません。

すべての Fragment 共有リンクは、その言語の一覧ページの共有画像を共用し、ID ごとの画像は生成しません。既定画像の変更は画像ガイドの共有画像説明を参照してください。

7. 同じ Fragment に翻訳を加える

簡体中国語と英語だけのひな形なら、先ほどの既定コマンドの代わりに次を使えます。

npm run new-fragment -- --locales zh,en

同じ実行で生成した言語ファイルは ID と日時を共有し、本文は自分で翻訳します。--locales は作成対象だけを選び、言語を有効にしません。優先順位は --locales → ANGLEFEINT_LOCALES 環境変数 → 有効言語で、省略時も自動翻訳は行いません。

既存の簡体中国語 Fragment に英語を追加するなら、元ファイルを src/content/fragments/en/ にコピーし、id と pubDate を残してタイトル・本文を翻訳します。新しい ID が発行されるため、同じ Fragment の翻訳に作成コマンドを再実行しないでください。異なる言語は同一 ID を共有できますが、同一言語には同 ID を2ファイル置けません。

同一 ID の翻訳はコメントを共有します。ID が異なれば文面やファイル名が同じでも自動的に関連付きません。

8. 必要に応じてコメントを有効にする

記録だけならコメントは無効のままで構いません。読者のコメントが必要ならGiscus ガイドで公開リポジトリ、Discussions、Giscus アプリ、カテゴリを用意し、実際の ID を得てから既存設定に統合します。

theme: {
  fragments: {
    enabled: true,
    comments: { enabled: true },
  },
  comments: {
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
  },
},

アカウント、リポジトリ、カテゴリ、2つの ID を実値に変え、既存の theme.comments の他設定を残してください。4つのリポジトリ・カテゴリ項目の不足は設定エラーです。仮値を入れても外部設定が有効とは限りません。Giscus script の貼付や追加 npm パッケージは不要です。

Fragment 用スイッチは theme.fragments.comments.enabled です。そのために記事用 theme.comments.enabled を true にする必要はありません。記事コメントがすでに有効なら維持して構いません。

Fragments は specific、厳密照合、fragment/<id> に固定し、記事の mapping、term、number、shareAcrossLocales、固定 lang は使いません。UI はページ言語に従い、同 ID の訳文は議論とリアクションを共有しますが、コメント本文の自動翻訳はありません。他の共通外観設定は theme.comments を使います。

一覧のコメントボタンを押して初めてクライアントを読みます。閉じてもインスタンスを維持し、再表示・別 Fragment で再利用します。失敗や約15秒未準備なら再試行を表示するため、読込表示を接続成功と見なさないでください。投稿には GitHub 認証が必要です。

ID を変更しても旧コメントは移行せず、Fragment を消しても GitHub の議論は削除しません。議論移行が必要なら自分で判断し、自動統合を期待しないでください。

9. 公開前の確認

dev で内容、日時、ホームのプレビュー、ページ分割を確認します。公開前に dev を止めて実行してください。

npm run doctor
npm run preview

doctor はローカル画像の準備・検証・ビルドを含み、成功直後の build は不要です。ビルド後の preview で共有リンクの移動と画像、設定した場合はコメントを確認します。プレビューでは公開せず、新しい静的出力を再配備して初めてオンラインが変わります。

Fragment は記事全文検索と記事 RSS には入りません。ビルドはその言語の /zh/fragments/index.md(他言語は zh を変更)に公開 Fragment をまとめ、ID、日時、本文、安定リンクを保持し、AI 可読索引にも加えます。私的バックアップではなく公開出力で、コメントは含みません。

  • 一覧がない:Fragments と対象言語のスイッチを確認。
  • ホームにアバターがない:現在の言語に実際の内容があるか確認。他言語にあっても現在言語にあるとは限りません。
  • 既存ファイルが原因で作成に失敗:既存 frontmatter の ID 形式を確認。作成器は Markdown の ID を読んで重複を確認します。
  • 重複 ID のビルドエラー:同じ言語に2ファイルを置いていないか確認。翻訳は別の言語ディレクトリに置きます。
  • 画像ビルド失敗:画像ガイドに従って元画像、マニフェスト、派生画像を準備・コミット。
  • コメント失敗:実際のリポジトリ ID、アプリ権限、カテゴリ、ネットワーク、ブラウザーの遮断を確認し、ID を繰り返し変えないこと。

更新が必要なら第1回の更新手順を参照してください。

ガイドと設定リファレンス

前の記事:記事と Fragments に画像を追加する · 次の記事:ページと機能を自分好みに変える · 8本のガイドの総合案内。

関連項目:Fragments のスイッチ、ページ分割、内容項目、Fragment のコメント。完全なパス、既定値、制約は設定リファレンス総合案内を参照してください。