Publishing on the Forge blog#

The Forge blog is the public editorial surface for engineering stories, product decisions, and measured release lessons. It is intentionally separate from the documentation and changelog:

• Blog posts explain why a capability exists, what changed while building it, and what was learned.
• Documentation and public specifications define supported behavior, limits, configuration, and APIs.
• Changelog entries record concise release facts and measurements.

Public routes:

• Blog index: https://forge.smol.ai/blog
• RSS feed: https://forge.smol.ai/blog/feed.xml
• Post permalink: https://forge.smol.ai/blog/<slug>

Add a post#

Every post has two compile-time sources.

1. Add public metadata to packages/content/src/blog.ts. The edge-owned catalog supplies the web index, article metadata, social cards, and RSS feed.
2. Add the Markdown body under packages/web/src/features/blog/posts/<slug>.md, then map it in packages/web/src/features/blog/blogCatalog.ts.

The build fails typechecking if the metadata shape is invalid. The catalog test also requires unique, newest-first permalinks and non-empty bodies.

Use a stable, descriptive slug. A published permalink is durable; edit the post in place for corrections rather than reusing or renaming its slug.

Editorial standard#

A Forge field note should:

1. put the bottom line first in a literal 2–8 word primary title;
2. use the optional subtitle for a short opinion, learning, or hook rather than hiding the outcome in wordplay;
3. make the description name the main technical achievement and its strongest production proof before background or process;
4. distinguish production measurements from estimates or targets;
5. explain the system boundary in plain language;
6. include a diagram, illustration, or compact evidence table when it makes the mechanism or comparison easier to understand;
7. describe Cloudflare as Forge's infrastructure provider, not a product Forge claims to replace;
8. state explicit limits and uncertainty;
9. link to the authoritative public specification; and
10. avoid credentials, private repository data, internal incident identifiers, or claims that were not proven on the owning production surface.

The Field Notes layout presents the shared author identity, publication date, reading time, and article body in one split-pane route. Put the most decision-relevant proof in the article itself as a compact table, diagram, or clearly scoped statement, and link to the durable engineering contract from the body. The catalog test enforces title length, shared author metadata, and proof-bearing structure, but editorial review still decides whether a title is genuinely literal and an illustration genuinely clarifies the system.

Validate before publishing#

npm test --workspace=packages/web
npm test --workspace=@cloudforge/content
npm test --workspace=@cloudforge/edge
npm run build --workspace=packages/web

Visually inspect /blog and the post permalink at mobile, tablet, desktop, and ultrawide widths in both light and dark themes. Confirm:

• no horizontal overflow;
• the index and permalink use the same optional-slug route and browser history returns cleanly to the index;
• the primary title, optional subtitle, and technical description remain a clear hierarchy;
• the article social-card URL in the server-rendered HTML;
• the post appears in /blog/feed.xml; and
• navigation distinguishes Blog, Docs, and Changelog.

After deployment, re-open the public permalink, RSS feed, social-card image, llms.txt, and /health. A successful build alone is not publication proof.