---
title: Components
description: Go beyond plain Markdown with built-in layout, callout, and media components that need no imports or extra packages.
---

You want a warning callout and a tabbed install snippet on the same page. Markdown headings and lists carry the prose, but the interactive layout comes from docs.page components you write directly in MDX.

## Overview

docs.page ships a library of **built-in MDX components** for structure, code, emphasis, reference fields, and media. They are available in every page under `docs/`. You do not install a package, add imports, or register components in `docs.json`.

Use plain Markdown when it is enough: paragraphs, lists, links, and fenced code blocks cover most writing. Reach for components when readers need switchable panels, numbered procedures, styled callouts, grouped code examples, API field rows, or embedded media.

The [Components](/components) tab is the lookup surface for props, child elements, and examples. This page explains what the library is and how docs.page recognizes component tags in your source files.

## How it works

### Global components, no imports

Author MDX with PascalCase JSX tags such as `<Tabs>`, `<Info>`, `<Steps>`, and the rest. docs.page parses those tags during bundling and maps each name to a React component in the renderer. Your page files never need `import` statements for the built-in set.

```mdx
<Warning>
  Back up your configuration before you change production settings.
</Warning>

<Tabs groupId="install">
  <TabItem label="npm" value="npm">...</TabItem>
  <TabItem label="pnpm" value="pnpm">...</TabItem>
</Tabs>
```

That tag is the contract: if docs.page recognizes the name, it renders with the site theme. If the name is unknown, the page shows an inline error instead of silently ignoring the tag.

### What is in the library

Components fall into a few roles. You mix them with normal Markdown inside the same file.

- **Structure and navigation:** `<Tabs>` and `<TabItem>` for switchable panels; `<Accordion>` and `<AccordionGroup>` for expandable detail; `<Steps>` and `<Step>` for numbered procedures; `<Card>` and `<CardGroup>` for linked overview tiles; `<Heading>` when you need explicit anchor behavior on a heading.
- **Code:** Fenced code blocks handle syntax highlighting, titles, and copy-to-clipboard. Wrap multiple fences in `<CodeGroup>` when readers should flip between languages or variants.
- **Callouts:** `<Info>`, `<Warning>`, `<Error>`, and `<Success>` replace a generic callout type. Pick the variant that matches the severity of the note.
- **Reference:** `<Property>` documents API and config fields with name, type, and required badges. Use it on Reference pages, not in tutorials.
- **Media:** `<Image>` for repo-relative images with optional light/dark variants and zoom; `<Icon>` for Font Awesome slugs; `<Video>`, `<YouTube>`, `<Vimeo>`, and `<Tweet>` (or `<X>`) for embedded media.

See the [Components overview](/components) for the full list and links to each component page.

### When to use components vs Markdown

| Need | Use |
| --- | --- |
| Body copy, lists, inline code | Plain Markdown |
| One code snippet with highlighting | Fenced code block |
| Platform or language variants | `<Tabs>` or `<CodeGroup>` |
| Prerequisites, cautions, tips | `<Info>`, `<Warning>`, or siblings |
| Tutorial or setup flow | `<Steps>` |
| Field-level API lookup | `<Property>` on Reference pages |
| Screenshots and embeds | `<Image>`, `<Video>`, `<YouTube>`, etc. |

Keep tutorials and how-tos focused on outcomes. Link to [Components](/components) for prop names and edge cases instead of copying reference tables onto feature or workflow pages.

### Same components in preview and production

Local preview bundles MDX the same way production does, so component tags you add under `docs/` render when you run `docs preview` before you push. Push-to-publish then serves those pages from GitHub with the same component map. No separate build step compiles JSX on your machine.

## Related

<CardGroup cols={2}>
  <Card title="Components overview" icon="cubes" href="/components">
    Props, child elements, and examples for every built-in component.
  </Card>
  <Card title="Write" icon="pen" href="/authoring/write">
    Structure pages with prose, links, code, and media in your workflow.
  </Card>
  <Card title="Page frontmatter" icon="file-lines" href="/reference/page-frontmatter">
    Frontmatter fields and how file paths under docs/ map to URL paths.
  </Card>
  <Card title="Public GitHub hosting" icon="github" href="/features/public-github-hosting">
    How committed MDX under docs/ is bundled and served on every push.
  </Card>
</CardGroup>