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
| Type | Purpose | Public route |
|---|---|---|
blog | Narrative articles, postmortems, and practical lessons | /blog and /content/:slug |
docs | Reference, runbook, contract, and how-to material | /docs and /content/:slug |
template | Structured 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
| Status | Meaning | Publicly indexed? |
|---|---|---|
draft | Work in progress, editable by the owner | No |
published | Current public version | Yes |
archived | Intentionally withdrawn from public discovery | No |
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
- Repository sources:
docs/contracts/public-content.md,src/lib/agent-content.ts, andsrc/lib/public-content.ts. - Metadata and sitemap conventions
- Route Handlers
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.