> 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/seo-and-metadata.md). # SEO And Metadata SEO and static metadata are centralized so individual pages do not duplicate head logic. ## Ownership | Concern | File | | ------------------------ | ------------------------------------------ | | Site origin and defaults | `src/data/site.ts` | | Metadata helpers | `src/lib/metadata.ts` | | Head tags | `src/components/seo/Seo.astro` | | JSON-LD script output | `src/components/seo/JsonLd.astro` | | Document shell | `src/layouts/BaseLayout.astro` | | RSS route | `src/pages/rss.xml.js` | | Robots | `public/robots.txt` | | Manifest | `public/site.webmanifest` | | Sitemap | `astro.config.mjs` with `@astrojs/sitemap` | ## Site Identity Current identity values in `src/data/site.ts`: | Field | Value | | -------------- | ----------------------------------------------- | | Name | `FactionOS` | | Alternate name | `Faction OS` | | Language | `en` | | Origin | `https://faction-os.com` | | Demo origin | `https://demo.faction-os.com` | | Docs origin | `https://faction-os.gitbook.io/faction-os-docs` | ## Metadata Defaults Default metadata includes: * title: `FactionOS` * title template: `%s | FactionOS` * description: local-first mission control positioning * locale: `en_US` * Open Graph type: `website` * Twitter card: `summary_large_image` * theme color: `#00d4ff` * color scheme: `dark light` * favicon: `/favicon.svg` * manifest: `/site.webmanifest` * RSS: `/rss.xml` * default social image from `brand.ogDefault` * robots default: `index, follow` ## Page Metadata Flow ``` Astro page props -> BaseLayout -> Seo.astro -> resolvePageMetadata() -> head tags and JSON-LD ``` Pages can override: * title * description * canonical path or canonical URL * robots policy * Open Graph type * social title/description/image * Twitter card * structured data If no override is provided, defaults from `src/data/site.ts` apply. ## Canonical URLs Canonical URLs are normalized by `src/lib/metadata.ts`. Rules: * Relative paths resolve against `https://faction-os.com`. * Hash fragments are removed. * Absolute URLs are allowed only when deliberately passed. * Home resolves to `https://faction-os.com/`. ## Robots Policy Default pages use `index, follow`. `LegalLayout.astro` supports legal/policy page robots settings. Legal pages are pre-review and may be noindex/no-follow depending on layout props and policy state. `public/robots.txt` points crawlers to the production sitemap. ## Open Graph And Twitter `Seo.astro` emits: * `og:site_name` * `og:locale` * `og:type` * `og:title` * `og:description` * `og:url` * `og:image` * `og:image:secure_url` * `og:image:type` * `og:image:width` * `og:image:height` * `og:image:alt` * `twitter:card` * `twitter:title` * `twitter:description` * `twitter:image` * `twitter:image:alt` The default social image is the 1200x630 `brand.ogDefault` asset in `src/lib/media.ts`. ## Structured Data Default structured data in `src/data/site.ts`: * Organization * WebSite * SoftwareApplication Article pages emit `BlogPosting` or `NewsArticle` through `PostLayout.astro`. FAQ data can emit `FAQPage` structured data from `src/data/faq.ts`. Structured data must stay conservative: * no hosted account claim * no customer metric claim * no certification claim * no hosted storage or trusted erasure claim * no production-hosted validation claim unless evidence exists ## RSS `src/pages/rss.xml.js` uses `@astrojs/rss`. Feed behavior: * combines blog and news entries * excludes drafts * newest first * limit 30 * uses absolute links * includes collection/category/tag categories Output path: ``` public-website/dist/rss.xml ``` ## Sitemap The sitemap integration is configured in `astro.config.mjs`. Output includes: ``` public-website/dist/sitemap-index.xml ``` The built-site checker validates the sitemap index, nested URL sets, and expected route coverage. ## Manifest And Favicon Static pass-through assets: ``` public-website/public/favicon.svg public-website/public/site.webmanifest ``` These are browser assets. Visible page media should not be placed in `public/` unless it is an intentional pass-through download with documented evidence. ## Validation Run: ```bash npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links ``` The checker validates: * expected fixed routes * blog/news generated routes * draft exclusion * RSS structure * sitemap structure * robots output * route metadata * canonical URLs * Open Graph metadata * Twitter metadata * approved internal/external links * legal pre-review markers * static privacy boundary ## Adding Or Changing Metadata When changing metadata behavior: 1. Update `src/data/site.ts` or route-level layout props. 2. Update `src/lib/metadata.ts` only if helper behavior changes. 3. Update `Seo.astro` only for emitted tag changes. 4. Update `PostLayout.astro` for article metadata changes. 5. Update the built-site checker if metadata expectations change. 6. Update this document. 7. Build and run `check:links`. --- # 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/seo-and-metadata.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.