---
title: Pages
description: Files and URLs, frontmatter, links, images and headings.
url: https://hexelstudio.com/docs/authoring/pages
---

## Files and URLs

Each page is one `.mdx` file in `content/docs`. Its path without the extension is its **slug**, and the slug is its URL:

| File | URL |
| --- | --- |
| `content/docs/get-started/quickstart.mdx` | `/docs/get-started/quickstart` |
| `content/docs/reference/theming.mdx` | `/docs/reference/theming` |

A page is published only when its slug is listed in `docs.config.ts`. See [Navigation](https://hexelstudio.com/docs/authoring/navigation).

## Frontmatter

Every page starts with a YAML block between `---` lines. Only `title` is required.

```mdx
---
title: Register an application
sidebarTitle: Registration
description: Configure the client, redirect URLs and API audience.
tag: New
---
```

<ResponseField name="title" type="string" required>
  The page heading, the browser title, and the label in navigation and search.
</ResponseField>
<ResponseField name="description" type="string">
  Shown under the title, in search results, in link previews and in `llms.txt`.
</ResponseField>
<ResponseField name="sidebarTitle" type="string">
  A shorter sidebar label for a long title.
</ResponseField>
<ResponseField name="tag" type="string">
  A small badge after the sidebar label, such as `New` or `Beta`.
</ResponseField>

## Links

Write links the way they appear in the browser, starting with `/docs`. This is also how Mintlify pages link, so moved pages keep working.

```mdx
See the [quickstart](https://hexelstudio.com/docs/get-started/quickstart), or jump to
[one of its sections](https://hexelstudio.com/docs/get-started/quickstart#before-you-push).
```

Links between pages navigate without a full reload. Links to other sites open in a new tab.

## Images

Put files in `public/` and reference them under `/docs`. `public/images/console.png` is served at `/docs/images/console.png`.

```mdx
![The Console home screen](https://hexelstudio.com/docs/images/console.png)

<Frame caption="The Console home screen">
  ![The Console home screen](https://hexelstudio.com/docs/images/console.png)
</Frame>
```

## Headings

Use `##` and `###` for sections. Each becomes an anchor (hover a heading to see its link) and an entry in **On this page**. A `####` heading gets an anchor but stays out of the list.

Do not start a page with `#`. The frontmatter title is the page's only top-level heading.

## Markdown

GitHub-flavored Markdown works: tables, task lists, ~~strikethrough~~, autolinks such as https://hexelstudio.com, and footnotes.[^1]

- [x] Tables
- [x] Task lists
- [ ] Anything that needs a raw `<` in prose: write it in backticks, because MDX reads `<` as the start of a component

[^1]: Footnotes collect at the end of the page.