> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/public-website/docs/archive-docs_public-website/content-authoring.md). # Content Authoring The website has two Astro content collections: * `blog` * `news` Schemas live in `src/content.config.ts`. Publishing helpers live in `src/lib/content.ts`. ## Collection Locations ``` public-website/src/content/blog/ public-website/src/content/news/ ``` Article routes are generated by: ``` src/pages/blog/[...slug].astro src/pages/news/[...slug].astro ``` Index routes are: ``` src/pages/blog/index.astro src/pages/news/index.astro ``` ## Blog Categories Allowed blog categories: * `product` * `architecture` * `field-notes` Category labels and descriptions live in `src/lib/content.ts`. ## News Categories Allowed news categories: * `release` * `changelog` * `demo` * `company` News entries may also include a `version`. ## Frontmatter Shared required fields: ```yaml --- title: "Clear title between 8 and 90 characters" description: "Description between 24 and 180 characters." pubDate: 2026-06-02 category: "product" tags: - Local-first - Agents --- ``` Shared optional fields: ```yaml updatedDate: 2026-06-02 draft: false author: "FactionOS Team" slug: "custom-kebab-slug" canonicalUrl: "https://example.com/original" heroImage: "./relative-or-imported-image.png" heroImageAlt: "Useful alt text for the hero image." ``` News-only optional field: ```yaml version: "website-0.0.23" ``` Rules enforced by schema: * `slug`, when provided, must be lowercase kebab-case. * `tags` must be readable alphanumeric labels. * `updatedDate` cannot be earlier than `pubDate`. * `heroImage` and `heroImageAlt` must be provided together. * `draft` defaults to `false`. * `author` defaults to `FactionOS Team`. ## Draft Behavior Drafts are included only when `includeDrafts` is true. By default: * Astro dev mode may include drafts. * Production build output excludes drafts. * RSS excludes drafts. * Sitemap should not include draft routes. * The built-site checker validates draft exclusion. Do not depend on manual review alone for draft exclusion. Build and run `check:links`. ## Current Blog Entries | File | Route | Category | | ------------------------------------ | --------------------------------------- | ------------ | | `introducing-factionos.md` | `/blog/introducing-factionos` | product | | `local-first-agent-observability.md` | `/blog/local-first-agent-observability` | architecture | | `why-agent-work-needs-a-cockpit.md` | `/blog/why-agent-work-needs-a-cockpit` | field-notes | | `hook-events-to-cockpit.md` | `/blog/hook-events-to-cockpit` | architecture | | `battlefield-cockpit-design.md` | `/blog/battlefield-cockpit-design` | field-notes | ## Current News Entries | File | Route | Category | | ---------------------------------- | ------------------------------------- | --------- | | `initial-public-website.md` | `/news/initial-public-website` | release | | `public-demo-available.md` | `/news/public-demo-available` | demo | | `factionos-public-site-expands.md` | `/news/factionos-public-site-expands` | company | | `website-publishing-polish.md` | `/news/website-publishing-polish` | changelog | ## RSS `src/pages/rss.xml.js` combines blog and news entries into one RSS feed. Behavior: * newest first * limit 30 * drafts excluded * absolute links generated from the configured site origin * categories include collection label, entry category label, and sorted tags ## Related And Neighbor Posts `src/lib/content.ts` computes: * featured entry * latest entry * category groups * related entries * previous/next neighbors * reading time Related entries score shared tags and same-category matches, then fall back to newest-first ordering. ## Authoring Guidelines Write with the same claim boundaries as product pages: * Say "static", "synthetic", "optional", "local", "outbound", or "pre-review" where the boundary matters. * Do not imply the public demo uses real user data. * Do not claim prompts, paths, credentials, source files, terminal output, replay data, or diagnostics upload by default. * Do not claim production-hosted validation without live deploy and smoke evidence. * Do not claim legal approval or formal certification without owner-approved evidence. * Link to docs and demo as external destinations, not as same-site routes. ## Adding A Blog Post 1. Create `src/content/blog/.md` or `.mdx`. 2. Use category `product`, `architecture`, or `field-notes`. 3. Add tags. 4. Keep `draft: true` until ready, if needed. 5. Run: ```bash npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links ``` ## Adding A News Entry 1. Create `src/content/news/.md` or `.mdx`. 2. Use category `release`, `changelog`, `demo`, or `company`. 3. Add `version` when the entry refers to a specific release or website package version. 4. Keep production claims scoped to available evidence. 5. Run the same validation commands as blog posts. ## Adding Hero Images Hero image use requires both: * `heroImage` * `heroImageAlt` Prefer website media recorded in `src/lib/media.ts` or package-local assets with documented provenance. Do not use unknown-provenance, generated-draft, or quarantined assets. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/public-website/docs/archive-docs_public-website/content-authoring.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.