diff --git a/optimize/seo.mdx b/optimize/seo.mdx index 080cd06ef..0dc130d58 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -82,7 +82,7 @@ If you're using a custom domain, set the `canonical` meta tag to ensure search e 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 @@ -96,7 +96,7 @@ The following meta tags are supported at the page level: - `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 @@ -114,7 +114,9 @@ keywords: ["keyword1", "keyword2"] ``` - 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"]`. ## Common meta tags reference @@ -124,7 +126,7 @@ Below is a comprehensive list of meta tags you can add to your `docs.json`. Thes The `og:image` adds a background image that Mintlify automatically overlays with your logo, page title, and description when generating social media previews. -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": { @@ -234,18 +236,22 @@ Only pages included in your `docs.json` are included by default. To include hidd ### 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 --- ``` + + Pages with `hidden: true` in their frontmatter are automatically treated as `noindex`. See [Hidden pages](/organize/hidden-pages) for details. + + You can also specify `noindex` for all pages in your docs by setting the `metatags.robots` field to `"noindex"` in your `docs.json`: ```json diff --git a/organize/hidden-pages.mdx b/organize/hidden-pages.mdx index 4fd9807cc..554b89f73 100644 --- a/organize/hidden-pages.mdx +++ b/organize/hidden-pages.mdx @@ -4,19 +4,13 @@ description: "Hide pages from your navigation while keeping them accessible." 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). @@ -24,9 +18,30 @@ See an [example of a hidden page](/organize/hidden-page-example). Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages. -## 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": [ @@ -47,11 +62,11 @@ A group of pages is hidden if the `hidden` property is set to `true` in your `do } ] ``` -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. -### 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": [ @@ -68,7 +83,7 @@ You can also hide a tab by adding the `hidden` property to your `docs.json` file ## 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": { diff --git a/organize/pages.mdx b/organize/pages.mdx index d2cc5e57b..ac35c3be6 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -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: @@ -23,7 +23,7 @@ Use frontmatter to control: - 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. @@ -42,7 +42,7 @@ Use frontmatter to control: - 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`. @@ -51,6 +51,14 @@ Use frontmatter to control: A tag that appears next to your page title in the sidebar. + + 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. + + + + 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. + + Any valid YAML frontmatter. For example, `product: "API"` or `version: "1.0.0"`. @@ -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 --- @@ -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 --- @@ -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 --- @@ -102,12 +110,12 @@ mode: "custom" ``` - 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. ### 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 --- @@ -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 --- @@ -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 --- @@ -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. - Meta tags with colons must be wrapped in quotes. + Always wrap meta tags with colons in quotes. ```yaml @@ -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 --- @@ -178,7 +186,7 @@ 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": { @@ -186,7 +194,7 @@ Add a "Last modified on [date]" timestamp to all pages by enabling `metadata.tim } ``` -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 --- @@ -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`.