GitDocAI lets you go beyond plain text by using interactive MDX components. Whether you want to organize content into multi-column layouts, guide users through step-by-step tutorials, or highlight important warnings, you can easily enhance your documentation to make it engaging and easy to read.

Every section below shows both the MDX syntax you write and a live preview so you know exactly what each component produces.

Structuring your pages

Card

A highlighted container that draws attention to related content. Perfect for feature grids, links to other pages, or short summaries with an optional icon.

Attributes: title, icon, iconAlign (left default or right), href (makes the whole card clickable).

MDX:

<Card title="Getting started" icon="pi pi-rocket" href="/quickstart">
Follow our 5-minute quickstart to publish your first documentation site.
</Card>

Preview:

Columns

Use the <Columns> component to create side-by-side comparisons, feature grids, or two-pane layouts. You can place plain text, images, or other components inside each <Column>.

By default, this creates a two-column layout. Adjust the columnCount attribute (1–3) if you need more or fewer columns.

MDX:

<Columns columnCount={2}>
  <Column>
    ### Before
    Manual writing, manual updates, manual publishing.
  </Column>
  <Column>
    ### After
    AI-generated, auto-synced, instantly published.
  </Column>
</Columns>

Preview:

Tabs

Tabs are perfect for showing alternative views of the same concept, such as instructions for different operating systems or alternative approaches to the same task.

MDX:

<Tabs>
  <Tab title="macOS" icon="pi pi-apple">
    Download the `.dmg` file and drag it to your Applications folder.
  </Tab>
  <Tab title="Windows" icon="pi pi-microsoft">
    Run the `.exe` installer and follow the setup wizard.
  </Tab>
</Tabs>

Preview:

Accordions

Collapsible sections help keep your pages clean by hiding content until the user expands it. They are ideal for FAQs, optional deep-dives, or troubleshooting steps.

By default, multiple panels can be open simultaneously. You can also disable a specific tab with the disabled attribute.

MDX:

<Accordion>
  <AccordionTab title="What is GitDocAI?">
    An AI-powered platform that generates and publishes documentation websites.
  </AccordionTab>
  <AccordionTab title="How long does setup take?" icon="pi pi-clock">
    Most users publish their first doc in under 10 minutes.
  </AccordionTab>
  <AccordionTab title="Enterprise SSO (coming soon)" disabled={true}>
    This feature is not yet available on your current plan.
  </AccordionTab>
</Accordion>

Preview:

Right Panel

Use <RightPanel> for supplementary context that floats alongside the main article — a quick reference card, a "did you know?" aside, or links to related pages. It stays visible without interrupting the main flow.

MDX:

<RightPanel>
## Quick reference

- **Cmd/Ctrl + J** — AI assistant
- **Cmd/Ctrl + Z** — undo
- **Esc** — close menus
</RightPanel>

Horizontal Rule

A visual divider between sections, used when headings alone don't create enough separation. Just three dashes on their own line.

MDX:

---

Preview:

Guiding users

Steps

When documenting a procedure where the order matters — like an installation guide or an onboarding flow — use the <Steps> component. It automatically numbers your sections and creates a clear, sequential guide.

MDX:

<Steps>
  <Step title="Install the CLI">
    Run `npm install -g @gitdocai/cli` in your terminal.
  </Step>
  <Step title="Authenticate">
    Run `gitdocai login` and follow the browser prompt.
  </Step>
  <Step title="Publish">
    Run `gitdocai publish` from your docs folder.
  </Step>
</Steps>

Preview:

1. 1

   Install the CLI

   Run npm install -g @gitdocai/cli in your terminal.

2. 2

   Authenticate

   Run gitdocai login and follow the browser prompt.

3. 3

   Publish

   Run gitdocai publish from your docs folder.

Callouts

Callouts draw attention to crucial information. GitDocAI uses standard GitHub-style admonition syntax.

MDX:

> [!TIP]
> You can press Cmd/Ctrl + J anywhere in the editor to open the AI assistant.

> [!DANGER]
> Revoking an API token will break any integration currently using it.

Preview:

Labels

Inline badges that mark feature status — Beta, Deprecated, Pro, version tags, or anything else you want to flag at a glance. Wrap multiple labels in <Labels> to group them.

Attributes: label (required), color (hex, default blue), size (sm / md / lg), icon (optional).

MDX:

<Label label="Beta" color="#8b5cf6" />

<Labels>
  <Label label="v2.0" color="#3b82f6" />
  <Label label="Stable" color="#10b981" icon="pi pi-check" />
  <Label label="Requires Pro" color="#f59e0b" />
</Labels>

Preview:

Displaying data

You have two options for building tables, depending on the size and complexity of your data.

flowchart TD
    A[Need to display a table?] --> B{More than 20 rows?}
    B -- Yes --> C[Use Advanced Table Component]
    B -- No --> D{Need pagination or scrolling?}
    D -- Yes --> C
    D -- No --> E[Use Standard Markdown Table]

Standard Markdown Tables

Best for small, static tables with fewer than 20 rows. They are fast to write and easy to read.

MDX:

| Plan | Documentations | AI requests |
|---|---|---|
| Free | 1 | 100 |
| Pro | 10 | 5,000 |

Preview:

Advanced Table Component

For larger datasets, use the <Table> component. It supports built-in pagination, scrolling, and a selectable page size. Pass your data as a 2D array, where the first row acts as the header.

Attributes: pagination, rowsPerPage, rowsPerPageOptions, scrollable, scrollHeight, data (required).

MDX:

<Table
  pagination={true}
  rowsPerPage={10}
  rowsPerPageOptions={[5, 10, 25]}
  data={[
    ["Name", "Email", "Status"],
    ["Ada Lovelace", "ada@example.com", "Active"],
    ["Alan Turing", "alan@example.com", "Active"]
  ]}
/>

Preview:

Code and media

Code blocks

To add syntax highlighting to your code snippets, specify the language immediately after the opening backticks. You can also add a filename to provide extra context.

MDX:

```js utils.js
export const add = (a, b) => a + b;
```

Preview:

export const add = (a, b) => a + b;

Code Groups

When you need to show the exact same code example in multiple languages (like an API request in curl, Python, and JavaScript), wrap your code blocks in a <CodeGroup>. This creates a tabbed interface specifically designed for code.

MDX:

<CodeGroup>

```bash curl
curl -X POST https://api.example.com/v1/docs 
  -H "Authorization: Bearer $TOKEN"
```

```javascript Node.js
await fetch('https://api.example.com/v1/docs', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});
```

</CodeGroup>

Preview:

curl -X POST https://api.example.com/v1/docs 
  -H "Authorization: Bearer $TOKEN"

await fetch('https://api.example.com/v1/docs', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});

Images

Embed images with standard Markdown syntax. The alt text shows up for screen readers and as a fallback if the image fails to load. You can also add an optional caption in quotes after the URL.

MDX:

![GitDocAI dashboard](/assets/dashboard.png "The editor interface with the sidebar and content area")

Preview:

The editor interface with the sidebar and content area

Adding icons

Many components (like <Card>, <Tab>, <AccordionTab>, <Step>, and <Label>) accept an icon attribute. GitDocAI supports several popular icon libraries. To use an icon, pass the corresponding class name:

• PrimeIcons: pi pi-bolt, pi pi-star, pi pi-check, pi pi-database, pi pi-server

• Font Awesome: fa fa-book, fa fa-rocket, fa fa-cog, fa fa-terminal, fa fa-users

• Material Icons: mi-code, mi-api, mi-settings, mi-security, mi-cloud

• Heroicons: hi-rocketLaunch-solid, hi-cog6Tooth-solid, hi-codeBracket-solid, hi-key-solid