Why `authoredAt`, `publishedAt`, and `updatedAt` belong in separate fields

An article has at least three relevant times: when the text took its present form, when it became eligible for publication, and when it was revised afterward. Putting all three into one date may seem simpler at first, but it leaves no way to distinguish a draft from a published article or a later update.

This site’s date-field contract, as documented in the original Traditional Chinese note, separates authoredAt, publishedAt, and updatedAt to give those content states distinct engineering boundaries. The rule is direct: each date should describe a different content event. One date cannot take on the responsibilities of the other two, and authoredAt must not automatically equal the file’s creation time.

What each field answers

The schema described in the original note gives the three fields different responsibilities:

Field	Question it answers	Use in the documented contract
authoredAt	When did this authored version take shape, in its writing context?	Optional; use a verifiable writing date rather than inferring it automatically from the file’s mtime.
publishedAt	From what point does this article qualify for public output?	Required for published articles; publication queries use it to determine eligibility and order.
updatedAt	When was this published article updated afterward?	Optional; requires publishedAt and must not precede it.

When present, publishedAt and updatedAt use YYYY-MM-DDTHH:mm:ss+08:00. Existing articles may retain a date-only authoredAt in YYYY-MM-DD format when that is the precision supported by evidence. For new articles written by the assistant under this policy, the actual Taipei-local time is recorded to the second when the first draft is complete. These fields correspond to different steps in the workflow; they are not interchangeable. The readable date on the page still shows only the day.

authoredAt follows the writing context

authoredAt should describe when an authored version of the article took shape. It is neither the creation time the operating system assigns to a file nor the date of the historical event the article discusses.

Three situations need to be kept separate:

• For an article newly written from the repository as it stands at the time of writing, record the actual Taipei-local date and time to the second in authoredAt when the first draft is complete. The existing batch discussed in the original note had no reliable second-level records, so those articles retained date-only values.
• If an article is a historical manuscript completed earlier, and an old draft, conversation, or other verifiable record supports its writing date, retain that actual date. This preserves the longer writing history.
• If an article written today reconstructs a development event from long ago, do not pass off the event date as the article’s authorship date. Put the event date in the body or an explanation of the evidence. Without a reliable original writing date, do not backfill a plausible one just to create a timeline.

A file’s creation date is therefore only a clue. It must not automatically become authoredAt. Whether a date is appropriate to make public depends on the event it represents, the evidence, and the article’s writing context at the time.

authoredAt is an editorial record, not publication eligibility

A draft can record authoredAt while leaving publishedAt: ''. The content schema treats the empty string as an unset publication date. This allows a local preview to show the writing date without the public homepage, notes list, or sitemap treating the article as publishable merely because the frontmatter contains the key.

The documented schema asks little of a draft: its metadata must be valid, draft defaults to true, and publishedAt can remain empty. That matches the writing process, because having a version of the text and having permission to publish it are different events.

Using authoredAt as a publication date would introduce a dangerous fallback: an article would appear to be published as soon as it was written. The site’s contract deliberately avoids that behavior. A published article must set draft to false and supply a real publishedAt; the schema rejects data that does only the former.

publishedAt is the boundary for public queries

Public output does not include every Markdown file simply because it exists. getPublishedNotes delegates to a shared publication selector. An article enters the public collection only if all of these conditions hold:

• draft is false.
• publishedAt exists.
• publishedAt is no later than today, calculated in the Taipei time zone.
• If a language is specified, the article’s locale matches it.

Eligible articles are sorted from newest to oldest using the second-level timestamp in publishedAt. Only when timestamps are exactly equal does stableId provide a stable order. So publishedAt affects more than the date shown on an article page: it also determines homepage ordering, list contents, whether an article detail page is generated, and whether the sitemap includes its URL.

A future date is not an automatic scheduling mechanism. A static site needs to be rebuilt after the date becomes eligible for the article to enter that build’s output. The date supplies a condition to evaluate; it does not trigger deployment.

updatedAt gives the latest update date, not the extent of the update

updatedAt has a narrower job: an article already has a publication date, and a later update needs to be recorded. The schema does not allow updatedAt without publishedAt, nor does it allow an update date earlier than publication.

The article template displays publishedAt and updatedAt separately. Readers can see that the article has been updated since its first publication without mistaking the update date for the original publication date.

The metadata described in the original note does not separately record which paragraphs changed or whether an update changed the article’s main judgment. updatedAt therefore establishes a date, not the scale, impact, or quality of the changes. If readers need to know why an article changed, explain that in the body or another public record. The date alone cannot tell them.

The template must preserve the distinction too

If the date contract stops at the schema, readers may still encounter dates with unclear meanings on the page. The article template described in the original note handles them according to content state:

• Published articles show publishedAt.
• If there is a later update, they also show updatedAt separately.
• In a local preview, a draft without publishedAt shows authoredAt, labeled as a preview date.

The same field should not change meaning from one page to another. A preview helps the author review a draft; a public page tells readers about publication status. They may use different date sources, but the labels and responsibilities must stay clear.

A checklist for writing

1. Decide which writing event authoredAt represents. For a newly written article, record the actual writing date and time under the first-draft completion rule above. For a historical manuscript, retain the original date only when evidence supports it. Do not guess from the file’s mtime.
2. Use the preview route to review the body locally. Do not treat the draft’s date as a publication date.
3. After receiving authorization to publish, replace publishedAt: '' with a real date and time in YYYY-MM-DDTHH:mm:ss+08:00 format, then set draft to false.
4. Only after a published article is modified again should you consider adding updatedAt, with a value no earlier than publishedAt.
5. Put the date of the subject event in the body or source explanation. Do not substitute it for the article’s writing date.
6. Do not infer traffic, search rankings, reader reactions, or business results from dates.

Separating these fields makes each date answer a specific question, rather than merely making the metadata look more complete. Authorship time belongs to the editorial record, publication time determines eligibility for public output, and update time adds information about recency. Keeping them separate also distinguishes when an article was written from the period of history it describes.

Scope of this record

This note presents the date-field contract documented in the original Traditional Chinese article, based on the note schema, publication selector, article template, existing tests, and writing guidelines described there. It explains field responsibilities and the boundaries of public output. It does not establish that any article has received authorization to publish, and it does not interpret date fields as indicators of SEO, traffic, or reader outcomes.