Docs · Web Blog / Public Content

Public Content Contract v1

Public Content Contract v1

This is the stable contract for published Blog, Docs, and Template content on docs.phatysd.me. It is written for agents, integrations, and maintainers who need to discover and consume content without scraping the human UI.

Content types

TypePurposePublic route
blogNarrative articles, postmortems, and practical lessons/blog and /content/:slug
docsReference, runbook, contract, and how-to material/docs and /content/:slug
templateStructured design template with profile, tokens, and live examples/templates and /content/:slug

The type is part of the published identity. Do not silently change a document into a blog or template without an explicit content revision and metadata review.

Lifecycle

StatusMeaningPublicly indexed?
draftWork in progress, editable by the ownerNo
publishedCurrent public versionYes
archivedIntentionally withdrawn from public discoveryNo

All public queries filter for status = 'published'. A draft or archived record must not appear in the homepage, search results, hierarchy pages, sitemap, llms.txt, JSON, or Markdown representation.

Stable URLs

Human canonical page: /content/:slug
Markdown:            /content/:slug/markdown
JSON:                /content/:slug/json
XML discovery:       /sitemap.xml
Agent discovery:     /llms.txt

The human page is canonical. The Markdown and JSON representations describe the same published item and must preserve its identity, revision, freshness, and body. A slug is canonical after publication and must not be changed casually; create a deliberate redirect/migration plan if a slug is ever wrong.

JSON contract

A successful JSON response contains:

{
  "id": 23,
  "type": "docs",
  "title": "Public Content Contract v1",
  "slug": "public-content-contract-v1",
  "canonicalUrl": "https://docs.phatysd.me/content/public-content-contract-v1",
  "status": "published",
  "revision": 1,
  "publishedAt": "2026-09-19T00:00:00.000Z",
  "updatedAt": "2026-09-19T00:00:00.000Z",
  "hierarchyPath": "Web Blog > Public Content",
  "topics": ["Content contract"],
  "tags": ["content", "json"],
  "related": [],
  "body": "# Public Content Contract v1\n..."
}

Template items additionally expose validated templateProfile, templateTokens, and templateExamples. A consumer should ignore fields it does not understand and should not infer template semantics from arbitrary CSS.

Missing content returns 404. Never use 200 with an empty body for a missing slug. Public responses must not expose drafts, archived rows, owner-only fields, database credentials, or internal authorization decisions.

Markdown contract

Markdown begins with machine-readable front matter containing the same identity fields using snake_case names such as canonical_url, published_at, updated_at, and revision. The authored Markdown body follows unchanged. Agents that need a text-first representation should prefer this endpoint over parsing HTML.

Revision semantics

Publishing a new version increments revision. The current row is updated and an immutable row is inserted into content_revisions. The revision number is monotonic per content item. Consumers can use it as a freshness signal, but should also compare updatedAt.

Discovery

llms.txt is a compact index of published content. sitemap.xml is the search-engine-oriented index. Both should contain only canonical public URLs. An agent can start at https://docs.phatysd.me/llms.txt, follow a content URL, then choose /markdown or /json according to the task.

Source of truth

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.