`authoredAt`、`publishedAt`、`updatedAt` を分ける理由

記事には、少なくとも三つの時点があります。文章が今の版としてまとまった時点、公開できるようになった時点、その後に修正された時点です。これらを一つの日付にまとめると、最初は簡単に見えても、後から下書き、公開済みの記事、その後の更新を区別できなくなります。

繁体字中国語の原稿に記録されたこのサイトの日時フィールドの契約では、authoredAt、publishedAt、updatedAt を分けています。フィールドを増やすことが目的ではなく、コンテンツの状態ごとに実装上の境界を設けるためです。日付はそれぞれ異なる出来事を表すべきで、一つの日付に残り二つの役割を代行させることはできません。authoredAt を機械的にファイルの作成日時と同じ値にすることもできません。

三つのフィールドが答える問い

原稿で説明されているスキーマでは、三つのフィールドにそれぞれ異なる役割があります。

フィールド	答える問い	記録された契約での扱い
authoredAt	この執筆版は、どのような執筆の文脈で、いつ形になったのでしょうか。	任意です。確認できる執筆日時を使い、ファイルの mtime から自動で推定しません。
publishedAt	この記事は、いつから正式な公開出力の条件を満たすのでしょうか。	公開記事では必須です。公開用のクエリが日時の判定と並び順に使います。
updatedAt	公開後、この記事はいつ更新されたのでしょうか。	任意です。先に publishedAt が必要で、公開日時より前にはできません。

publishedAt と updatedAt に値を入れる場合は、YYYY-MM-DDTHH:mm:ss+08:00 を使います。既存記事の authoredAt は、根拠が日付までしかない場合、YYYY-MM-DD のまま保持できます。この方針に沿って助手が新しく執筆する記事では、初稿が完成した実際の台北時間を秒単位で記録します。三つのフィールドは異なる工程に対応しているため、互いに置き換えられません。一方、ページ上で人が読む日付は、引き続き日単位までの表示です。

authoredAt は執筆の文脈に合わせます

authoredAt が表すのは、記事の執筆版が形になった時点です。OS がファイルに付ける作成日時でも、記事が扱う歴史上の出来事の日付でもありません。

次の三つを区別する必要があります。

• 執筆時点のリポジトリをもとに新しく記事を書く場合は、初稿が完成した実際の台北日時を秒単位で authoredAt に記録します。原稿で扱っていた既存記事群には、信頼できる秒単位の記録がなかったため、日付だけを保持していました。
• 以前に完成した原稿で、古い下書き、会話、その他の確認できる記録がある場合は、その実際の執筆日を保持できます。そうすることで、長期にわたる執筆の経緯を残せます。
• かなり前の開発上の出来事を今日あらためて整理する場合、出来事の日付を記事の執筆日として扱ってはいけません。出来事の時点は本文や根拠の説明に記載します。元の執筆日時を確認できないなら、時系列を整えるためだけに、もっともらしい日付を後から入れるべきではありません。

したがって、ファイルの作成日は手がかりにはなりますが、自動的に authoredAt になるものではありません。その日付を公開してよいかどうかは、何の出来事を表すのか、どのような根拠があるのか、当時どのような文脈で記事を書いたのかによって判断します。

authoredAt は編集記録であり、公開資格ではありません

下書きでは、先に authoredAt を記録し、publishedAt: '' を残しておけます。コンテンツのスキーマは、この空文字列を公開日時が未入力の状態として扱います。そのため、ローカルプレビューには執筆日を表示しつつ、frontmatter にこのキーがあるだけで、正式なホームページ、記事一覧、sitemap が公開対象として扱うことを防げます。

記録されたスキーマが下書きに求める条件は少なく、メタデータが有効であれば、draft の既定値は true で、publishedAt は空欄のままにできます。文章に一つの版ができたことと、公開の許可を得たことは別なので、この扱いは実際の執筆フローに合っています。

authoredAt を公開日時の代わりに使うと、書き終えただけの記事が公開済みのように扱われる、危険なフォールバックが生まれます。このサイトの契約では、意図的にその扱いを避けています。公開記事では draft を false に設定し、実際の publishedAt も記録する必要があります。前者だけで後者がないデータは、スキーマが拒否します。

publishedAt は公開用クエリの境界です

正式な出力は、Markdown ファイルが存在するというだけですべてを生成するものではありません。getPublishedNotes は共通の公開セレクターに判定を渡し、次の条件をすべて満たす記事だけが公開対象の集合に入ります。

• draft が false であることが必要です。
• publishedAt が存在することが必要です。
• publishedAt は、台北のタイムゾーンで計算した今日より後であってはいけません。
• 言語を指定した場合は、記事の locale が一致する必要があります。

条件を満たした記事は、publishedAt の秒単位の日時を使って、新しいものから古いものへ並びます。日時が完全に一致した場合にだけ、stableId で順序を安定させます。つまり、publishedAt は記事ページに表示する日付だけではありません。ホームページの並び順、一覧の内容、記事詳細ページを生成するかどうか、sitemap に URL を載せるかどうかにも関わります。

未来の日時を指定しても、自動で公開を予約できるわけではありません。静的サイトでは、日付の条件を満たしてから再ビルドすることで、その回の出力に記事が入ります。日時は判定の根拠を提供しますが、それ自体がデプロイを実行することはありません。

updatedAt が伝えるのは更新日時であり、変更の大きさではありません

updatedAt の役割は限定されています。記事に正式な公開日時があり、その後の更新を記録するためのフィールドです。スキーマは、publishedAt のない updatedAt を許可しません。更新日時を公開日時より前にすることも許可しません。

記事テンプレートは、publishedAt と updatedAt を別々に表示します。これにより、読者は初回公開後に更新された記事だとわかり、更新日時を元の公開日時と取り違えずに済みます。

原稿で説明されているメタデータには、どの段落を変更したのか、今回の更新で主要な判断が変わったのかを別途記録するフィールドはありません。したがって、updatedAt が示せるのは日時であって、変更の規模、影響、品質ではありません。変更理由を読者に伝える必要があるなら、本文や別の公開記録で説明します。日付だけから理由を導き出すことはできません。

テンプレートでも日時の違いを保ちます

日時の契約をスキーマだけで定義しても、ページ上で意味が混ざれば読者には伝わりません。原稿で説明されている記事テンプレートは、状態に応じて表示を分けています。

• 公開記事には publishedAt を表示します。
• その後の更新があれば、updatedAt も別に表示します。
• ローカルプレビューで publishedAt のない下書きを見る場合は、authoredAt を表示し、プレビュー用の日付だと明示します。

同じ日時フィールドが、ページによって別の意味に変わってはいけません。プレビューは作者の校正を助けるためのもので、正式なページは読者に公開状態を伝えるためのものです。参照する日時が違っていても、ラベルと役割は明確に保つ必要があります。

執筆時に確認する順序

1. authoredAt がどの執筆を表すのか、先に決めます。新しく書く記事には、前述の初稿完成時のルールに従って実際の執筆日時を記録します。過去の原稿は、根拠がある場合にだけ元の日付を保持します。ファイルの mtime から日付を推測しません。
2. ローカルで校正する場合は、プレビュールートで本文を確認します。下書きの日付を公開日時として扱いません。
3. 正式な公開の許可を得てから、publishedAt: '' を実際の YYYY-MM-DDTHH:mm:ss+08:00 の日時に置き換え、draft を false にします。
4. 公開済みの記事を再び修正した場合にだけ、updatedAt を記録するか検討します。その値は publishedAt 以降である必要があります。
5. 記事が扱う出来事の日付は、本文や出典の説明に別途記載します。記事の執筆日時の代わりには使いません。
6. 日付から、アクセス数、検索順位、読者の反応、事業上の成果を推測しません。

こうして分ける目的は、メタデータを充実して見せることではなく、それぞれの日付で明確な問いに答えることです。執筆日時は編集記録に属し、公開日時は公開対象になる資格を決め、更新日時は記事の新しさを補足します。三つを分けることで、記事がいつ書かれたのかと、どの時代の出来事を説明しているのかも区別できます。

この記録の範囲

この記事は、繁体字中国語の原稿に記録された note のスキーマ、公開セレクター、記事テンプレート、既存のテスト、執筆規則をもとに、日時フィールドの契約を説明しています。対象は各フィールドの役割と公開出力の境界です。個々の記事に公開の許可が出ていることを示すものではなく、日時フィールドを SEO、アクセス数、読者への効果の指標として解釈するものでもありません。