Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion create/text.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Format text"
description: "Learn how to format text, create headers, and style content."
keywords: ["Markdown formatting", "text styling", "headers", "anchor links"]
keywords: ["Markdown formatting", "text styling", "headers", "anchor links", "custom heading IDs"]
---

## Headers
Expand All @@ -22,6 +22,23 @@
Use descriptive, keyword-rich headers that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
</Tip>

### Custom heading IDs

By default, anchor IDs are generated automatically from header text. You can override the generated ID with a custom one using the `{#custom-id}` syntax:

Check warning on line 27 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L27

In general, use active voice instead of passive voice ('are generated').

```mdx
## My section {#my-custom-anchor}
### Configuration options {#config}
```

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.

<Note>
Custom heading IDs are supported on heading levels 1 through 4 (`#` to `####`). Levels 5 and 6 are not supported.

Check warning on line 39 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L39

In general, use active voice instead of passive voice ('are supported').
</Note>

### Disabling anchor links

By default, headers 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 headers.
Expand Down Expand Up @@ -64,8 +81,8 @@

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

Check warning on line 84 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L84

Use 'Strikethrough' instead of 'strikethrough'.
*~~italic and strikethrough~~*

Check warning on line 85 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L85

Use 'Strikethrough' instead of 'strikethrough'.
```

**_bold and italic_**<br />
Expand Down
12 changes: 11 additions & 1 deletion guides/linking.mdx
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: "Linking"
description: "Learn how to create internal links, reference API endpoints, and maintain link integrity across your documentation."
keywords: ["internal links", "cross-references", "anchor links", "broken links", "deep linking"]
keywords: ["internal links", "cross-references", "anchor links", "broken links", "deep linking", "custom heading IDs"]
---

Effective linking creates a connected documentation experience that helps users discover related content and navigate efficiently. Too many links or broken links can confuse users and make your documentation less effective. This guide covers how to create and maintain links throughout your documentation.

## Internal links

Link to other pages in your documentation using root-relative paths. Root-relative paths start from the root of your documentation directory and work consistently regardless of where the linking page is located.

Check warning on line 11 in guides/linking.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/linking.mdx#L11

In general, use active voice instead of passive voice ('is located').

```mdx
* [Quickstart guide](/quickstart)
Expand Down Expand Up @@ -46,7 +46,7 @@
* [Customize your playground](/api-playground/overview#customize-your-playground)
* [Cards properties](/components/cards#properties)

### How anchor links are generated

Check warning on line 49 in guides/linking.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/linking.mdx#L49

In general, use active voice instead of passive voice ('are generated').

Anchor links are automatically created from header text.

Expand All @@ -65,6 +65,16 @@
Headers with the `noAnchor` prop do not generate anchor links. See [Format text](/create/text#disabling-anchor-links) for details.
</Note>

### Custom anchor IDs

You can override the auto-generated anchor for any heading by appending `{#custom-id}` to the header text:

```mdx
## Configuration options {#config}
```

This heading is reachable at `#config` instead of `#configuration-options`. Custom IDs are useful for keeping anchor links stable when you update heading text. See [Format text](/create/text#custom-heading-ids) for more details.

## Deep linking

Deep links point to specific states or locations within a page, not just the page itself. Use deep links to send users directly to an open accordion or an API playground view.
Expand All @@ -73,7 +83,7 @@

When a user opens an accordion, the URL hash updates to reflect the open state. Visiting a URL with that hash automatically opens and scrolls to the accordion.

By default, the hash is derived from the accordion's `title`. Use the `id` property to set a custom hash:

Check warning on line 86 in guides/linking.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/linking.mdx#L86

In general, use active voice instead of passive voice ('is derived').

```mdx
<Accordion title="Installation steps" id="install">
Expand All @@ -99,7 +109,7 @@

## Link to API endpoints

When documenting APIs, you can link to specific endpoints from anywhere in your documentation.

Check warning on line 112 in guides/linking.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/linking.mdx#L112

Did you really mean 'APIs'?

Link to API endpoint pages using their path in the navigation.

Expand Down
Loading