Skip to content

Document hidden frontmatter property #3377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 6 commits into from
Feb 10, 2026
+72 −43
Merged

Document hidden frontmatter property #3377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
65a6d58
add note about hidden pages to SEO page
ethanpalm Feb 10, 2026
19b491b
add fronmatter props to pages.mdx
ethanpalm Feb 10, 2026
ac22678
vale
ethanpalm Feb 10, 2026
69d9acf
vale
ethanpalm Feb 10, 2026
118b809
add frontmatter option to hidden pages
ethanpalm Feb 10, 2026
3469036
vale
ethanpalm Feb 10, 2026
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
22 changes: 14 additions & 8 deletions optimize/seo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@
}
```

### Set a canonical URL

Check warning on line 69 in optimize/seo.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

optimize/seo.mdx#L69 

'Set a canonical URL' should use sentence-style capitalization.

If you're using a custom domain, set the `canonical` meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

Expand All @@ -82,7 +82,7 @@

To set page-specific meta tags, add them to a page's frontmatter.

The following meta tags are supported at the page level:
Page-specific meta tags include:
- `title` - Page title
- `description` - Page description appears below the title on the page and in some search engine results
- `keywords` - Comma-separated keywords
Expand All @@ -96,7 +96,7 @@
- `twitter:title` - Twitter card title
- `twitter:description` - Twitter card description
- `twitter:image` - Twitter card image
- `twitter:card` - Twitter card type like "summary" or "summary_large_image"
- `twitter:card` - Twitter card type like `summary` or `summary_large_image`
- `twitter:site` - Twitter site handle
- `twitter:image:width` - Twitter image width
- `twitter:image:height` - Twitter image height
Expand All @@ -114,7 +114,9 @@
```

<Note>
Meta tags with colons must be wrapped in quotes. The `keywords` field must be formatted as a YAML array.
You must wrap meta tags with colons in quotes. For example, `og:title: "Social media title"`.

You must format the `keywords` field as a YAML array. For example, `keywords: ["keyword1", "keyword2", "keyword3"]`.
</Note>

## Common meta tags reference
Expand All @@ -124,7 +126,7 @@
The `og:image` adds a background image that Mintlify automatically overlays with your logo, page title, and description when generating social media previews.
</Note>

You can preview how your meta tags will appear on different platforms using [metatags.io](https://metatags.io/).
You can preview how your meta tags appear on different platforms using [metatags.io](https://metatags.io/).

```json expandable
"seo": {
Expand Down Expand Up @@ -234,18 +236,22 @@

### Custom sitemaps and robots.txt files

To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `robots.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.
To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `robots.txt` file at the root of your project. Adding a custom file overrides the automatically generated file of the same name. If you delete a custom file, the default file automatically applies again.

## Disabling indexing
## Disable indexing

If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/organize/pages) of your page:
To prevent search engines from indexing a page, add `noindex: true` to the [frontmatter](/organize/pages) of the page.

```
```yaml
---
noindex: true
---
```

<Tip>
Pages with `hidden: true` in their frontmatter are automatically treated as `noindex`. See [Hidden pages](/organize/hidden-pages) for details.
</Tip>

You can also specify `noindex` for all pages in your docs by setting the `metatags.robots` field to `"noindex"` in your `docs.json`:

```json
Expand Down
47 changes: 31 additions & 16 deletions organize/hidden-pages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,44 @@
keywords: ["hide from navigation", "unlisted", "page visibility"]
---

Hidden pages are not included in your site's navigation but remain publicly accessible to anyone who knows their URL.
Hidden pages don't appear in your site's navigation, but anyone who knows the URL can still access them. For example, if you create a hidden page like `guides/hidden-page.mdx`, visitors can reach it at `docs.yoursite.com/guides/hidden-page`.

Use hidden pages for content that you want to be accessible on your site or referenced as context for AI tools, but not discoverable through the navigation.
Use hidden pages for content you want users to access or reference as context for AI tools, but don't want listed in the navigation.

For content requiring strict access control, you must configure [authentication](/deploy/authentication-setup).
If your content requires strict access control, you must configure [authentication](/deploy/authentication-setup).

To restrict pages to specific groups of users, configure [group-based access control](/deploy/authentication-setup#control-access-with-groups).

## Hiding a page

To hide a page, remove it from your navigation structure. Any pages that are not included in your `docs.json` navigation are hidden.

Hidden pages use the same URL structure as regular pages based on their file path. For example, `guides/hidden-page.mdx` would be accessible at `docs.yoursite.com/guides/hidden-page`.
To restrict pages to specific user groups, set up [group-based access control](/deploy/authentication-setup#control-access-with-groups).

See an [example of a hidden page](/organize/hidden-page-example).

<Note>
Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
</Note>

## Hiding a group of pages
## Hide a page

To hide a page, set `hidden: true` in the page's [frontmatter](/organize/pages) or remove it from your `docs.json` navigation.

### Set `hidden: true` in frontmatter

Add `hidden: true` to a page's frontmatter to remove it from the rendered navigation while still including it in your `docs.json` configuration.

```yaml
---
title: "My hidden page"
hidden: true
---
```

Search engines cannot index pages with `hidden: true`. See [Disable indexing](/optimize/seo#disabling-indexing) for more information.

### Remove the page from navigation

If you don't include a page in your `docs.json` navigation, you hide it. This method works well for pages that you don't want to appear in navigation at all.

## Hide a group of pages

A group of pages is hidden if the `hidden` property is set to `true` in your `docs.json` file:
To hide a group of pages, set the `hidden` property to `true` for the group in your `docs.json` file:

```json highlight={4}
"groups": [
Expand All @@ -47,11 +62,11 @@
}
]
```
In this example, the `Getting started` group is hidden, but the `Guides` group is visible.
In this example, the `Getting started` group is hidden and the `Guides` group is visible.

Check warning on line 65 in organize/hidden-pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/hidden-pages.mdx#L65 

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

### Hiding a tab
### Hide a tab

You can also hide a tab by adding the `hidden` property to your `docs.json` file:
To hide a tab, add the `hidden` property for the tab in your `docs.json` file:

```json highlight={4}
"tabs": [
Expand All @@ -68,7 +83,7 @@

## Search, SEO, and AI indexing

By default, hidden pages are excluded from indexing for search engines, internal search within your docs, and as context for the AI assistant. To include hidden pages in search results and as context for the assistant, add the `seo` property to your `docs.json`:
By default, hidden pages don't appear in indexing for search engines, documentation site search, or as AI assistant context. To include hidden pages in search results and assistant context, add the `seo` property to your `docs.json`:

```json
"seo": {
Expand Down
46 changes: 27 additions & 19 deletions organize/pages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ description: "Configure page metadata, titles, and frontmatter properties."
keywords: ["tags", "tag", "frontmatter", "metadata", "layout"]
---

Each page is a Markdown file. Both `.mdx` and `.md` file types are supported. We recommend using MDX, which combines Markdown with React components to create rich, interactive documentation. Plain Markdown (`.md`) is supported for easier migration from other platforms, but should be updated to MDX for full functionality.
Each page is a Markdown file. You can use either `.mdx` or `.md` file types for your pages. We recommend MDX, which combines Markdown with React components for rich, interactive documentation. Plain Markdown (`.md`) can expedite migration from other platforms, but switching to MDX enables more features.

## Page metadata

Every page starts with frontmatter, the YAML metadata enclosed by `---` at the beginning of a file. This metadata defines how your page appears and behaves.
Every page begins with frontmatter, the YAML metadata enclosed by `---` at the top of a file. This metadata controls how your page appears and behaves.

Use frontmatter to control:

Expand All @@ -23,7 +23,7 @@ Use frontmatter to control:
</ResponseField>

<ResponseField name="description" type="string">
A brief description of what this page covers. Appears under the title and improves SEO.
A brief description of what this page covers. Displays under the title and improves SEO.
</ResponseField>

<ResponseField name="sidebarTitle" type="string">
Expand All @@ -42,7 +42,7 @@ Use frontmatter to control:
</ResponseField>

<ResponseField name="iconType" type="string">
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
For [Font Awesome](https://fontawesome.com/icons) icons only. The style of the icon.

Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
</ResponseField>
Expand All @@ -51,6 +51,14 @@ Use frontmatter to control:
A tag that appears next to your page title in the sidebar.
</ResponseField>

<ResponseField name="hidden" type="boolean">
Set to `true` to remove the page from the sidebar navigation. Users can still access the page via its URL, but search engines do not index it. See [Hidden pages](/organize/hidden-pages) for details.
</ResponseField>

<ResponseField name="noindex" type="boolean">
Set to `true` to prevent search engines from indexing the page. See [Disable indexing](/optimize/seo#disable-indexing) for details. All pages with `hidden: true` in their frontmatter receive `noindex: true` automatically.
</ResponseField>

<ResponseField name="<custom>" type="string">
Any valid YAML frontmatter. For example, `product: "API"` or `version: "1.0.0"`.
</ResponseField>
Expand All @@ -67,11 +75,11 @@ tag: "NEW"

## Page mode

Control how your page displays with the `mode` setting.
Control your page's layout with the `mode` setting.

### Default

If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents.
If you do not define a mode, the page uses a standard layout with sidebar navigation and table of contents.

```yaml
---
Expand All @@ -81,7 +89,7 @@ title: "Default page title"

### Wide

Wide mode hides the table of contents. This is useful for pages that do not have any headings or if you prefer to use the extra horizontal space. Wide mode is available for all themes.
Wide mode hides the table of contents. Use this mode for pages without headings or if you want extra horizontal space. Every theme supports wide mode.

```yaml
---
Expand All @@ -92,7 +100,7 @@ mode: "wide"

### Custom

Custom mode provides a minimalist layout that removes all elements except for the top navbar. Custom mode is a blank canvas to create landing pages or any other unique layouts that you want to have minimal navigation elements for. Custom mode is available for all themes.
Custom mode provides a minimalist layout and removes all elements except for the top navbar. Treat custom mode as a blank canvas to build landing pages or unique layouts with minimal navigation. All themes support custom mode.

```yaml
---
Expand All @@ -102,12 +110,12 @@ mode: "custom"
```

<Warning>
Using the `style` property on custom mode pages can cause a layout shift on page load. Use [Tailwind CSS or custom CSS](/customize/custom-scripts) instead to avoid this issue.
The `style` property on custom mode pages may cause a layout shift on page load. Prefer [Tailwind CSS or custom CSS](/customize/custom-scripts) to avoid this issue.
</Warning>

### Frame

Frame mode provides a layout similar to custom mode, but preserves the sidebar navigation. This page mode allows for custom HTML and components while maintaining the default navigation experience. Frame mode is only available for Aspen and Almond themes.
Frame mode provides a layout similar to custom mode but keeps the sidebar navigation. Use this mode to include custom HTML and components while preserving the default navigation experience. Only Aspen and Almond themes support frame mode.

```yaml
---
Expand All @@ -118,7 +126,7 @@ mode: "frame"

### Center

Center mode removes the sidebar and table of contents, centering the content. This is useful for changelogs or other pages where you want to emphasize the content. Center mode is available for Mint and Linden themes.
Center mode removes the sidebar and table of contents, and centers the content. Use center mode for changelogs or other pages where you want to place focus on the content. Mint and Linden themes support center mode.

```yaml
---
Expand All @@ -129,7 +137,7 @@ mode: "center"

## API pages

Create interactive API playgrounds by adding an API specification to your frontmatter, `api` or `openapi`.
To create an interactive API playground, add an API specification to your frontmatter by setting `api` or `openapi`.

```yaml
---
Expand All @@ -152,10 +160,10 @@ url: "https://www.npmjs.com/package/mint"

## Search engine optimization

Most SEO meta tags are automatically generated. You can set SEO meta tags manually to improve your site's SEO, social sharing, and browser compatibility.
Mintlify automatically generates most SEO meta tags. You can set SEO meta tags manually to customize your approach to SEO, social sharing, and browser compatibility.

<Note>
Meta tags with colons must be wrapped in quotes.
Always wrap meta tags with colons in quotes.
</Note>

```yaml
Expand All @@ -164,11 +172,11 @@ Most SEO meta tags are automatically generated. You can set SEO meta tags manual
---
```

See [SEO](/optimize/seo) for complete SEO metadata options.
See [SEO](/optimize/seo) for the full list of SEO metadata options.

## Internal search keywords

Enhance a specific page's discoverability in the built-in search by providing `keywords` in your metadata. These keywords won't appear as part of the page content or in search results, but users that search for them will be shown the page as a result.
Help users discover a specific page in search results by providing `keywords` in your metadata. These keywords don't appear in page content. If users search for the keywords, the page appears in the search results.

```yaml
---
Expand All @@ -178,15 +186,15 @@ keywords: ['configuration', 'setup', 'getting started']

## Last modified timestamp

Add a "Last modified on [date]" timestamp to all pages by enabling `metadata.timestamp` in your [global settings](/organize/settings#metadata).
Show a "Last modified on [date]" timestamp on all pages by enabling `metadata.timestamp` in your [global settings](/organize/settings#metadata).

```json docs.json
"metadata": {
"timestamp": true
}
```

Override the global timestamp setting on individual pages with the `timestamp` frontmatter field. Use this field to selectively show or hide timestamps on specific pages.
To override the global timestamp setting for an individual page, use the `timestamp` frontmatter field. Use this field to show or hide timestamps on specific pages.

```yaml
---
Expand All @@ -195,4 +203,4 @@ timestamp: false
---
```

When set to `true`, the timestamp displays even if the global setting is `false`. When set to `false`, the timestamp is hidden even if the global setting is `true`.
If you set `timestamp: true`, the page always shows the timestamp even if the global setting is `false`. If you set `timestamp: false`, the page hides the timestamp even if the global setting is `true`.