From 329115565e684ca6da70ead715c23525dfcc08c4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 2 Jul 2025 16:53:27 -0700 Subject: [PATCH 1/2] update Pages --- pages.mdx | 170 +++++++++++++++++++++--------------------------------- 1 file changed, 67 insertions(+), 103 deletions(-) diff --git a/pages.mdx b/pages.mdx index fa53544d..d941e38d 100644 --- a/pages.mdx +++ b/pages.mdx @@ -4,170 +4,134 @@ description: "Pages are the building blocks of your documentation" icon: "letter-text" --- -## Basics +Each page is an MDX file, which combines Markdown content with React components to let you create rich, interactive documentation. -Each page is an MDX file that should begin with `---` at the start and end. This is used to define the page's metadata, such as the title and description. +## Page metadata -For example, you can define the title for this page as follows. +Every page starts with frontmatter—YAML metadata enclosed by `---` at the beginning of your file. This metadata controls how your page appears and behaves. -```mdx ---- -title: "Your title goes here" ---- -``` - -## Descriptions - -You can add a description that shows the summary of the page under the title with the `description` metadata. + + The title of your page that appears in navigation and browser tabs. + -```mdx ---- -description: "Your description goes here" ---- -``` + + A brief description of what this page covers. Appears under the title and improves SEO. + -## Sidebar Title + + A short title that displays in the sidebar navigation. + -If you want to show a different title in the navigation, you can set the `sidebarTitle` metadata. This is useful if your title is long and you want something shorter in the navigation links. - -```mdx ---- -title: "Your very long page title you want to shorten" -sidebarTitle: "Short title" ---- -``` + + An icon next to your page title in the sidebar. Choose an icon from Font Awesome, Lucide, or use a custom URL. Configure your preferred icon library with the [icons library setting](/settings#param-icons). -## Icons + -Add an icon next to your page's sidebar title by including the `icon` field in your page's frontmatter. + + A tag that appears next to your page title in the sidebar. + -```mdx +```yaml Example YAML frontmatter wrap --- -title: "Code Block" -icon: "code" +title: "About frontmatter" +description: "Frontmatter is the metadata that controls how your page appears and behaves" +sidebarTitle: "Frontmatter" +icon: "book" +tag: "NEW" --- ``` -You can set icons from a URL, [Font Awesome](https://fontawesome.com/icons), or [Lucide](https://lucide.dev/icons). Choose your preferred icon library (Font Awesome or Lucide) with the [icon library setting](settings#param-icons). +## Page mode -For Font Awesome icons, you can optionally set the icon type. If not set, the icon type will be regular. - -```mdx ---- -iconType: "solid" ---- -``` +Control how your page displays with the `mode` setting. -## Tag +### Default -Add tags to label specific pages. Tags display in the sidebar next to page titles. +If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents. -```mdx ---- -tag: "NEW" +```yaml +title: "Default page title" --- ``` -## API Pages - -API pages let you build interactive API playgrounds. To create an API page, you -must set an `api` or `openapi` property in the page metadata. +### Wide -Learn more about API pages by visiting the [API page guides](/api-playground/overview). +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. -```mdx +```yaml --- -openapi: "GET /endpoint" +title: "Wide page title" +mode: "wide" --- ``` -## Page Mode - -The Page Mode setting allows you to customize the appearance of your page. You can choose from -different modes to adjust the layout according to your needs. If no mode is specified, the page -will use the default settings. +### Custom -### Default - -If no specific mode is given, the page will default to standard settings. This means the page -will display the default table of contents and other standard elements. +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. -```mdx +```yaml --- -title: "Default page title" +title: "Custom page title" +mode: "custom" --- ``` -### Wide Mode +### Center -In Wide Mode, you can hide the table of contents (ToC) on the right side of the page. This is -particularly useful if your page doesn’t have any headings or if you prefer to utilize the -extra horizontal space for more content. +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. -```mdx +```yaml --- -mode: "wide" +title: "Center page title" +mode: "center" --- ``` -### Custom Mode +## API pages -Custom Mode provides a minimalist layout by removing all elements except for the top bar. -This mode offers a blank canvas, which is ideal for creating a "landing page" or any page where -you want a clean, distraction-free environment. +Create interactive API playgrounds by adding an API specification to your frontmatter, `api` or `openapi`. -```mdx +```yaml --- -mode: "custom" +openapi: "GET /endpoint" --- ``` -### Center Mode - -Center Mode removes the sidebar and the table of contents, and centers the page content. This mode is great for changelogs -or any page where you want to focus on the content. - -```mdx ---- -mode: "center" ---- -``` +Learn more about building [API documentation](/api-playground/overview). -## External Links +## External links -If you want the sidebar to open an external URL, you can set the `url` metadata -in any page. +Link to external sites directly from your navigation with the `url` metadata. -```mdx +```yaml --- -title: "Page that goes to external link" +title: "npm Package" url: "https://www.npmjs.com/package/mint" --- ``` -## Search Engine Optimization +## Search engine optimization -You can set meta tags like the image set when shared on social media by passing -them into your page's metadata. +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. -Note that meta tags with colons need to be wrapped in quotes. + + Meta tags with colons must be wrapped in quotes. + -```mdx +```yaml --- -"twitter:image": "/images/your-photo.jpg" +"twitter:image": "/images/social-preview.jpg" --- ``` -See [SEO](/settings/seo) to learn more about SEO metadata. +See [SEO](/settings/seo) for complete SEO metadata options. -## Internal Search Optimization +## Internal search keywords -You can also 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. +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. -```mdx +```yaml --- -keywords: ['search', 'indexing'] +keywords: ['configuration', 'setup', 'getting started'] --- -``` \ No newline at end of file +``` From c96f9505d42659f88c722c1a5956d78ccb04fd4a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 2 Jul 2025 16:54:36 -0700 Subject: [PATCH 2/2] fix code sample --- pages.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/pages.mdx b/pages.mdx index d941e38d..242f9f5e 100644 --- a/pages.mdx +++ b/pages.mdx @@ -50,6 +50,7 @@ Control how your page displays with the `mode` setting. If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents. ```yaml +--- title: "Default page title" --- ```