Knowledge Base
Writing Docs
Conventions for pages, frontmatter, and navigation.
Writing docs
Edit your documentation repository when you want to change page source, navigation, or image files together in a pull request. This guide covers repository-backed Pageloop docs sites. For editing in the app instead, see Working in the Knowledge Base.
Page files and MDX
Start in the folder containing docs.json, the docs root. Pages use .mdx or .md files; use .mdx when adding pages that combine Markdown and components. For example, a file named guides/setup.mdx contains the setup page, while docs.json controls where that page appears in navigation.
MDX combines Markdown headings, paragraphs, lists, links, tables, and fenced code blocks with built-in components such as <Note> and <Steps>. Put YAML frontmatter at the beginning of the file, followed by the page body.
Use the components below without importing them. Match component names and capitalization exactly, close each tag, and use literal property values such as title="Install" or cols={2}. Do not add JavaScript expressions, event handlers, or imports to a page.
Do not edit generated API pages by hand. Pages marked generated: openapi or generated: asyncapi come from their API specification.
Set the title and description
Use frontmatter to give the page a readable title and a short summary:
---
title: Set up your workspace
description: Connect your documentation and prepare your workspace for review.
---
# Set up your workspace
Connect your documentation before preparing changes for review.titlenames the page. Keep it specific enough to distinguish the page from nearby articles.descriptionsummarizes what the reader can do or learn. Keep it useful without repeating the title.
Frontmatter is metadata, not body text. Keep the opening and closing --- lines on their own lines.
Add the page to navigation
Creating a file does not add it to the sidebar. Add a page entry to the appropriate group in docs.json in the same pull request.
For a site that uses top-level navigation, the structure looks like this:
{
"site": {
"name": "Example Docs"
},
"navigation": [
{
"group": "Knowledge Base",
"pages": [
{
"page": "guides/working-in-the-knowledge-base"
}
]
}
]
}This example assumes guides/working-in-the-knowledge-base.mdx exists beneath the docs root. In your repository, add the entry to the existing configuration rather than replacing the file with this minimal example.
- A
pagevalue is the file path relative to the docs root, without.mdxor.mdand without a leading slash. groupsupplies the sidebar category label;pagescontains its ordered entries. Groups can contain other groups.- Every page reference must resolve to an existing file. List each page once.
- Keep
docs.jsonvalid JSON: use double quotes and omit comments and trailing commas. - If the site uses
tabsorversions, preserve that structure and edit the appropriate navigation block. Do not add a competing top-levelnavigationarray.
Moving a navigation entry changes its sidebar placement, not the page's file path or public address.
Add and reference images
- Add the image file beneath the docs root, for example in
images/orimages/uploads/. PNG, JPEG, GIF, and WebP are supported choices. - Commit the image together with the page that uses it.
- Reference the image with its path from the docs root and include descriptive alt text.
For example, after adding images/setup.png, use:
Use a leading slash to make the path explicit. The image resolver matches paths against synced repository assets; do not treat an image reference as relative to the page's directory or use ../images/setup.png from a nested page. An unresolved image produces a warning and is omitted from the rendered page.
To add a frame and caption, wrap the image in Frame:
<Frame caption="Connect your documentation before preparing a draft.">
<img src="/images/setup.png" alt="Workspace setup showing the documentation connection" />
</Frame>Replace the example filename and alt text with your own image and description. Check that screenshots show the intended interface and do not expose personal information or credentials.
Use built-in components
Choose components for the information they organize. Keep ordinary explanations as Markdown rather than putting every paragraph in a component.
Callouts
Use Note for context, Info for supporting information, Tip for advice, and Warning or Danger for cautions.
<Note>
Saving a draft does not publish your changes.
</Note>Cards
Use Card for a linked summary. Wrap related cards in CardGroup to arrange them together:
<CardGroup cols={2}>
<Card title="Edit in the Knowledge Base" href="/guides/working-in-the-knowledge-base">
Organize pages and review unpublished changes in Pageloop.
</Card>
<Card title="Check a pull request" href="/guides/pull-request-checks">
Read validation results before merging repository changes.
</Card>
</CardGroup>Steps
Use Steps with a Step for each stage of an ordered task:
<Steps>
<Step title="Edit the source">
Update the page file and any related navigation or images.
</Step>
<Step title="Review the proposal">
Open a pull request and inspect the rendered result and check findings.
</Step>
</Steps>Tabs
Use Tabs with a Tab for each alternative, not for consecutive steps:
<Tabs>
<Tab title="Repository">
Edit the page's MDX file on your proposal branch.
</Tab>
<Tab title="Knowledge Base">
Open the page in Pageloop and use Markdown source to edit its source.
</Tab>
</Tabs>Accordions
Use Accordion for details readers can expand. Use AccordionGroup to collect related items:
<AccordionGroup>
<Accordion title="Does saving publish my page?">
No. Review the draft and complete the publishing flow separately.
</Accordion>
<Accordion title="Does moving a sidebar entry change its URL?">
No. Navigation placement and the page address are separate.
</Accordion>
</AccordionGroup>Code blocks
Use a fenced code block with a language identifier for syntax highlighting. An optional title labels the example:
```json title="Page navigation entry"
{
"page": "guides/working-in-the-knowledge-base"
}
```Use CodeGroup when readers should choose between related code examples:
<CodeGroup>
```bash title="List page files"
ls guides
```
```bash title="Inspect changes"
git diff
```
</CodeGroup>Slugs, links, and redirects
By default, the public path comes from the page's file path, lowercased and without the extension. A trailing index becomes its containing directory: guides/index.mdx serves at /guides, and the root index.mdx serves at /.
A frontmatter slug overrides the whole public path, not just the last segment. Navigation entries still identify the page file. Use the served path for reader-facing links, such as [Review checks](/guides/pull-request-checks).
Changing a title or sidebar category is not a URL change. Treat file renames and slug changes as address changes: review internal links and redirects rather than assuming the old URL remains available. See Working in the Knowledge Base: change a slug without losing old links for the Edit slug… and Redirects… controls, automatic old-address redirects, and when those changes go live.
Check changes before merging
- Review the complete pull request, including page source,
docs.json, images, and links. Open a preview when available and inspect the rendered components and images, not just the source diff. - If an Admin has enabled Pull request checks for your connected repository, read Pageloop's result on the GitHub pull request or GitLab merge request for the latest commit.
- Fix publishing blockers such as invalid
docs.jsonor navigation entries that point to missing pages. Review warnings too: broken links and invalid MDX can reach readers even when the check passes. - Push corrections and check the updated result before merging. A check that could not run is not a clean result.
See Check documentation pull requests for setup, result meanings, merge requirements, and how to request Fix with Pageloop. Keep the change as a reviewed proposal until your repository's review and merge process is complete.

