How to Add a New Docs Page

How to Add a New Docs Page

This guide covers everything you need to add a new .mdx page to xrmghost-docs and have it appear in the user portal.

1. Find the Right Product Owner

Before writing anything, confirm your change falls within your team’s ownership area:

1. Open Content Ownership.
2. Locate the section that matches the content you want to add (e.g. src/content/docs/cli/, src/content/docs/attributes/).
3. Check the Owning Team column.
4. If the section does not exist yet or the owner is unclear, contact the Documentation team as interim owner.

If you are adding a net-new section (a new product area), align with the Documentation team first so the ownership table can be updated in the same PR.

2. Choose the Right Folder

The src/content/docs/ folder hierarchy mirrors the site navigation. Follow these naming rules:

Rule	Example
Use lowercase, hyphen-separated folder names	src/content/docs/my-product/
Each section must have an index.mdx as its landing page	src/content/docs/my-product/index.mdx
Sub-sections live in nested folders	src/content/docs/my-product/advanced/index.mdx
Do not invent deeply nested hierarchies speculatively — start flat	src/content/docs/my-product/getting-started.mdx

If a folder already exists for your product area, add your page there. Do not create a parallel folder.

3. Create the File

Create a new .mdx file in the appropriate folder. The file name should be lowercase and hyphen-separated.

src/content/docs/my-product/my-new-page.mdx

4. Write the Frontmatter

Every .mdx file must begin with a YAML frontmatter block. Two fields are required:

---
title: My New Page
description: A one-sentence summary of what this page covers.
---

Frontmatter Rules

Field	Required	Notes
title	Yes	Shown in navigation and browser tab. Keep it short (≤ 60 chars).
description	Yes	One sentence. Used in SEO meta tags and link previews.
Additional fields	No	Only add fields that the portal’s MDX pipeline explicitly supports. Do not invent fields.

The build will reject any .mdx file that is missing title or description.

5. Write Honest Content

• If the content is not ready, use an explicit TODO marker rather than inventing placeholder content:

  > **TODO:** This section will be expanded in [story/ticket reference].

• Fake or hallucinated content is harder to fix than an honest placeholder and misleads readers.

• Cite the ADO story ID when the TODO has a known follow-up owner.

5.1 Template Learnings from the First Real Docs Slice

The first repo-level public docs slice for src/content/docs/attributes/ exposed a few reusable lessons for future work:

• Start from a real package surface, not the template headings. Pull examples and terminology from the source package README or code so the first draft is anchored in what actually exists.
• Separate narrative guidance from generated reference early. If exhaustive schema pages are not available yet, document the package purpose and usage shape now, and reserve a future location such as src/content/docs/<area>/schema/ for generated content later.
• Use bounded TODOs only for missing reference material. Narrative basics such as purpose, audience, and a starter example should be written as soon as they are known; TODO markers should remain limited to honestly missing generated or machine-derived content.
• Record template gaps when they appear. If a placeholder page required extra explanation about source-of-truth boundaries or future generated content, add that guidance here so the next team does not rediscover it from scratch.

5.2 CLI Docs Contributor Decision Path

When making CLI-related documentation changes, choose your path based on what you are changing:

Path A — Narrative-only change (stays in xrmghost-docs)

You are editing the conceptual overview, getting-started guide, or any human-written explanation of the CLI.

• Files: src/content/docs/cli/index.mdx, src/content/docs/cli/getting-started.mdx (or other narrative files outside src/content/docs/cli/reference/).
• Where to work: This repository (xrmghost-docs).
• PR target: xrmghost-docs dev.
• Reviewer: Documentation team or CLI team.
• Do not touch src/content/docs/cli/reference/ files in this PR.

Path B — Generator or source-driven change (starts in xrmghost-cli)

You are changing a CLI command, its --help text, its flags, or the command manifest that feeds the reference generator.

• Where to work: xrmghost-cli repository.
• PR target: xrmghost-cli (its own review and merge process).
• Effect on xrmghost-docs: After the xrmghost-cli change merges and the generator runs, updated files land under src/content/docs/cli/reference/ automatically. Do not manually replicate those changes in xrmghost-docs.
• Reviewer: CLI team in xrmghost-cli. Approval in xrmghost-docs does not substitute for approval in xrmghost-cli.

Path C — Coordinated docs-plus-generator change (linked workstream or single shared PR)

You need to update both the CLI source/generator in xrmghost-cli and narrative or contract documentation in xrmghost-docs as part of the same logical change (for example, a new command that also needs a narrative walkthrough, or a generator contract change that also updates architecture docs).

• Acceptable approach: A single shared PR or coordinated workstream that touches both repositories is acceptable when both sides must move together.
• Required: The PR or workstream description must clearly identify which changes are narrative (owned by xrmghost-docs) and which are source/generator changes (owned by xrmghost-cli), with appropriate reviewers from each team.
• Not acceptable: Using a shared PR as a bypass to skip xrmghost-cli review for generator or source changes, or to manually edit generated files in src/content/docs/cli/reference/ without running the generator.
• Do not let the shared PR scope drift into editing generated reference files directly. Generated content under src/content/docs/cli/reference/ must always originate from the generator run, not from hand edits.

See Content Ownership — CLI Ownership Boundary for the authoritative ownership split, and Generated vs Manual — CLI Generation Contract for the full generation rules.

6. Open a Pull Request

1. Branch off dev using the naming convention docs/<short-description> (or the swarm branch convention if operating in a swarm run).
2. Add only the files you own or have been given permission to touch.
3. Request a review from at least one person on the owning team (see Content Ownership).
4. Pass CI checks (frontmatter lint, MDX parse).
5. Merge to dev after approval.

7. Publishing to the Portal

Publishing is controlled by the xrmghost-user-portal team. After your PR merges to dev:

• The portal team advances the submodule pointer (or runs the sync script) to pick up your changes.
• You do not need to take action in the portal repository unless you are also the portal maintainer.

For details on how the portal consumes this repo, see Source of Truth.

Summary Checklist

• Confirmed correct product owner in Content Ownership
• File placed in the correct src/content/docs/ subfolder
• File name is lowercase and hyphen-separated
• Frontmatter includes title and description
• No fake content — used > **TODO**: markers where content is missing
• PR targets dev, reviewer from owning team assigned