# Format text (/create/text)

<!-- agent-signals: reading_time_min: 8 · est_tokens: 3000 · updated: 2026-07-30 -->
Related: [Changelogs](/create/changelogs.md), [Format code](/create/code.md), [Files](/create/files.md), [Images and embeds](/create/image-embeds.md), [Lists and tables](/create/list-table.md), [Personalized content](/create/personalization.md)

## Headings [#headings]

Headings organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation.

### Create headings [#create-headings]

Use `#` symbols to create headings of different levels:

```mdx
## Main section heading
### Subsection heading
#### Sub-subsection heading
```

Use `##` (H2) through `######` (H6) for content sections. The title set in a page's [frontmatter](/organize/pages) applies a title heading, `#` (H1). Do not use top-level `#` headings inside a page.

<Tip>
  Use descriptive, keyword-rich headings that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
</Tip>

### Automatic anchor IDs [#automatic-anchor-ids]

By default, Mintlify generates an anchor ID from the heading text. Generated IDs use the following rules:

* Mintlify converts letters to lowercase and whitespace to hyphens.
* Mintlify converts straight apostrophes to right single quotation marks (`’`) and keeps them in the ID.
* Mintlify converts periods to hyphens and removes parentheses.
* Mintlify converts capital letters within a word to lowercase without adding hyphens.
* Mintlify preserves slashes and ampersands.

When a page has multiple headings that generate the same ID, Mintlify adds `-2`, `-3`, and so on. The counter applies across the entire page, including headings nested inside components such as tabs.

The following examples show how heading text maps to a generated anchor ID:

| Heading text                 | Generated ID             |
| :--------------------------- | :----------------------- |
| `Getting started`            | `getting-started`        |
| `Config.json options`        | `config-json-options`    |
| `What's new`                 | `what’s-new`             |
| `Rate limits (per minute)`   | `rate-limits-per-minute` |
| `Read/write access`          | `read/write-access`      |
| `Fees & billing`             | `fees-&-billing`         |
| `OAuth`                      | `oauth`                  |
| Duplicate `Overview` heading | `overview-2`             |

<Note>
  Mintlify's anchor IDs do not use GitHub-style slugging. Percent-encode non-ASCII characters when constructing a URL programmatically.
</Note>

### Custom heading IDs [#custom-heading-ids]

To override the generated ID with a custom one, use the `{#custom-id}` syntax.

```mdx
## My section [#my-custom-anchor]
### Configuration options [#config]
##### Deep detail [#detail]
```

The custom ID replaces the auto-generated anchor, so you can link to the heading with `#my-custom-anchor` or `#config` instead of the default slugified text.

This is useful when you want stable anchor links that don't change if you update the heading text, or when you need shorter, more memorable anchors.

### Disable anchor links [#disable-anchor-links]

By default, headings include clickable anchor links that allow users to link directly to specific sections. You can disable these anchor links using the `noAnchor` prop in HTML or React headings.

<CodeGroup>
  <CodeBlockTabs defaultValue="HTML heading example" groupId="html-heading-example+react-heading-example">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="HTML heading example">
        HTML heading example
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="React heading example">
        React heading example
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="HTML heading example">
      ```mdx  
      <h2 noAnchor>
      Heading without anchor link
      </h2>
      ```
    </CodeBlockTab>

    <CodeBlockTab value="React heading example">
      ```mdx  
      <Heading level={2} noAnchor>
      Heading without anchor link
      </Heading>
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

When `noAnchor` is used, the heading does not display the anchor chip and clicking the heading text does not copy the anchor link to the clipboard.

## Text formatting [#text-formatting]

Mintlify supports most Markdown formatting for emphasizing and styling text.

### Basic formatting [#basic-formatting]

Apply these formatting styles to your text:

| Style             | Syntax     | Example                | Result                 |
| ----------------- | ---------- | ---------------------- | ---------------------- |
| **Bold**          | `**text**` | `**important note**`   | **important note**     |
| *Italic*          | `_text_`   | `_emphasis_`           | *emphasis*             |
| ~~Strikethrough~~ | `~text~`   | `~deprecated feature~` | ~~deprecated feature~~ |

### Combine formats [#combine-formats]

You can combine formatting styles:

```mdx
**_bold and italic_**
**~~bold and strikethrough~~**
*~~italic and strikethrough~~*
```

***bold and italic***<br /&#x3E;
&#x2A;*~~bold and strikethrough~~**<br /&#x3E;
&#x2A;~~italic and strikethrough~~*

### Superscript and subscript [#superscript-and-subscript]

For mathematical expressions or footnotes, use HTML tags:

| Type        | Syntax            | Example               | Result              |
| ----------- | ----------------- | --------------------- | ------------------- |
| Superscript | `<sup>text</sup>` | `example<sup>2</sup>` | example<sup>2</sup> |
| Subscript   | `<sub>text</sub>` | `example<sub>n</sub>` | example<sub>n</sub> |

## Links [#links]

Links help users navigate between pages and access external resources. Use descriptive link text to improve accessibility and user experience.

### Internal links [#internal-links]

Link to other pages in your documentation using root-relative paths. Omit the file extension (`.mdx` or `.md`). Relative paths and paths with extensions do not work in production.

```mdx
[Quickstart](/quickstart)
[Steps](/components/steps)
```

[Quickstart](/quickstart)<br />
[Steps](/components/steps)

### External links [#external-links]

For external resources, include the full URL:

```mdx
[Markdown Guide](https://www.markdownguide.org/)
```

[Markdown Guide](https://www.markdownguide.org/)

### Broken links [#broken-links]

You can check for broken links in your documentation using the [CLI](/cli):

```bash
mint broken-links
```

## Block quotes [#block-quotes]

Block quotes highlight important information, quotes, or examples within your content.

### Single line block quotes [#single-line-block-quotes]

Add `>` before text to create a block quote:

```mdx
> This is text that stands out from the main content.
```

> This is text that stands out from the main content.

### Multi-line block quotes [#multi-line-block-quotes]

For longer quotes or multiple paragraphs:

```mdx
> This is the first paragraph of a multi-line block quote.
>
> This is the second paragraph, separated by an empty line with `>`.
```

> This is the first paragraph of a multi-line block quote.
>
> This is the second paragraph, separated by an empty line with `>`.

<Tip>
  Use block quotes sparingly to maintain their visual impact and meaning. Consider using [callouts](/components/callouts) for notes, warnings, and other information.
</Tip>

## Mathematical expressions [#mathematical-expressions]

Mintlify supports LaTeX for rendering mathematical expressions and equations. You can override automated detection by configuring `styling.latex` in your `docs.json` [settings](/organize/settings-appearance#styling).

### Inline math [#inline-math]

Use single dollar signs, `$`, for inline mathematical expressions:

```mdx
The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
```

The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.

### Block equations [#block-equations]

Use double dollar signs, `$$`, for standalone equations:

```mdx
$$
E = mc^2
$$
```

$$
E = mc^2
$$

<Info>
  LaTeX support requires proper mathematical syntax. Refer to the [LaTeX documentation](https://www.latex-project.org/help/documentation/) for comprehensive syntax guidelines.
</Info>

## Line breaks and spacing [#line-breaks-and-spacing]

Control spacing and line breaks to improve content readability.

### Paragraph breaks [#paragraph-breaks]

Separate paragraphs with blank lines:

```mdx
This is the first paragraph.

This is the second paragraph, separated by a blank line.
```

This is the first paragraph.

This is the second paragraph, separated by a blank line.

### Manual line breaks [#manual-line-breaks]

Use HTML `<br />` tags for forced line breaks within paragraphs:

```mdx
This line ends here.<br />
This line starts on a new line.
```

This line ends here.<br />
This line starts on a new line.

<Tip>
  In most cases, paragraph breaks with blank lines provide better readability than manual line breaks.
</Tip>

### Horizontal rules [#horizontal-rules]

Use Markdown `---` syntax or HTML `<hr />` tags to add a horizontal rule that visually separates sections of content:

```mdx
Content preceding the rule.

<hr />

Content following the rule.
```

Content preceding the rule.

<hr />

Content following the rule.

<Tip>
  Use horizontal rules sparingly. In most cases, headings provide better content separation with the added benefit of navigation anchors.
</Tip>

## Comments [#comments]

Use MDX-style comments to add notes, reminders, or to-dos in your source files. Comments don't render in the published page.

```mdx
{/* This is a comment and won't appear in the published docs. */}

{/*
  Multi-line comments work too.
  Useful for TODOs or reviewer notes.
*/}
```

<Warning>
  HTML-style `<!-- ... -->` comments are not supported in MDX. Always use `{/* ... */}`.
</Warning>

## Escape special characters [#escape-special-characters]

MDX treats `{` and `}` as the start and end of JSX expressions, and `<` as the start of a JSX tag. When you want these characters to render as literal text, escape them so MDX does not try to parse them.

| Character   | How to escape                                                                                                                                                     |
| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{` and `}` | Wrap the character in backticks (`` `{` ``), use the HTML entity (`&#123;` for `{`, `&#125;` for `}`), or write it inside a JSX expression as a string (`{'{'}`). |
| `<`         | Wrap in backticks (`` `<` ``), use the HTML entity `&lt;`, or write `{'<'}`.                                                                                      |
| `` ` ``     | Use a backslash (`` \` ``).                                                                                                                                       |
| `\`         | Use a double backslash (`\\`).                                                                                                                                    |

```mdx title="Escape examples"
Use the `{variable}` syntax to interpolate values.

The placeholder &#123;name&#125; renders as literal curly braces.

In JSX, write {'{ key: value }'} to display a literal object.
```

Inside fenced code blocks (` ``` `), MDX does not parse curly braces, so you can write `{variable}` directly without escaping. Escaping is only required in regular prose and inside JSX attributes.

## Best practices [#best-practices]

### Content organization [#content-organization]

* Use headings to create clear content hierarchy
* Follow proper heading hierarchy (don't skip from H2 to H4)
* Write descriptive, keyword-rich heading text

### Text formatting [#text-formatting-1]

* Use bold for emphasis, not for entire paragraphs
* Reserve italics for terms, titles, or subtle emphasis
* Avoid over-formatting that distracts from content

### Links [#links-1]

* Write descriptive link text instead of "click here" or "read more"
* Use root-relative paths for internal links
* Test links regularly to prevent broken references