Every page in Wupxy Docs follows the same frontmatter structure and body conventions. This page is the reference for adding new content.

​
Frontmatter

Every .mdx file must start with these three fields: 
---
title: "Page title"
description: "One sentence describing what the reader can do after reading this page."
icon: "icon-name"
---
FieldRequiredNotes
titleYesAppears in sidebar, page H1, and <title> tag
descriptionYesShown as subtitle and used for meta description
iconYesLucide icon name (kebab-case). Browse at lucide.dev
Description writing rule: Start with a verb. “Run the automation loop and review daily output” is better than “This page covers the automation loop.”

​
Body structure

Use H2 (##) for top-level sections. Do not use H1 — the frontmatter title becomes the page H1. Keep sections short. If a section runs longer than 10 lines of prose, consider whether it belongs in its own page. End most guide pages with a “What’s next” card or callout pointing to the logical next step.

​
Available components

​
Cards and columns

Use <Columns> with <Card> to create a linked card grid: 
<Columns cols={2}>
  <Card title="Title" icon="icon-name" href="/path">
    Short description.
  </Card>
  <Card title="Title" icon="icon-name" href="/path">
    Short description.
  </Card>
</Columns>
Use cols={2} for two items. Use cols={3} for three. Card href is optional — omit it for informational cards.

​
Steps

Use <Steps> for sequential instructions where order matters: 
<Steps>
  <Step title="Step title">
    Step content. Describe what the user does, not what the system does.
  </Step>
  <Step title="Step title">
    More content.
  </Step>
</Steps>
Each <Step> can contain prose, code blocks, or nested components.

​
Callouts

Four callout types for different purposes: 
<Tip>Use for best practices and shortcuts.</Tip>

<Info>Use for neutral context that helps understanding.</Info>

<Warning>Use for actions that can cause data loss or hard-to-reverse changes.</Warning>

<Check>Use to confirm a required state or verification step.</Check>

​
Accordion

Use <Accordion> for optional detail that interrupts the main reading path: 
<Accordion title="Optional detail title">
  Content that is useful but not required for the primary path.
</Accordion>
Common uses: failure modes, edge cases, reference tables.

​
Code blocks

Use fenced code blocks with a language specifier for syntax highlighting: 
```bash
npm run build
```

```typescript
const value = getResult();
```

```yaml
---
title: "Example"
---
```
Do not nest triple-backtick fences inside another triple-backtick fence — this closes the outer fence early. Use prose to describe nested code examples or use 4-backtick outer fences.

​
Naming conventions

ItemConventionExample
File nameKebab-caseproject-scoping.mdx
Folder nameKebab-caseworkflows/
Page titleTitle case"Project Scoping"
Tab nameTitle case"Workflows"
Group nameTitle case"Project Delivery"

​
Adding a page to navigation

After creating the .mdx file, add its path (without extension) to the correct group in docs.json: 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Workflows",
        "groups": [
          {
            "group": "Project Delivery",
            "pages": [
              "workflows/project-scoping",
              "workflows/your-new-page"
            ]
          }
        ]
      }
    ]
  }
}
The path is relative to the wupxy-docs/ root, without the .mdx extension.