mintlify · ethanpalm · Jul 2, 2025 · Jul 2, 2025
diff --git a/pages.mdx b/pages.mdx
@@ -4,170 +4,135 @@
 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"
----
-```
+<ResponseField name="title" type="string" required>
+  The title of your page that appears in navigation and browser tabs.
+</ResponseField>
 
-## Descriptions
+<ResponseField name="description" type="string">
+  A brief description of what this page covers. Appears under the title and improves SEO.
+</ResponseField>
 
-You can add a description that shows the summary of the page under the title with the `description` metadata.
+<ResponseField name="sidebarTitle" type="string">
+  A short title that displays in the sidebar navigation.
+</ResponseField>
 
-```mdx
----
-description: "Your description goes here"
----
-```
+<ResponseField name="icon" type="string">
+  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).
 
-## Sidebar Title
+</ResponseField>
 
-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.
+<ResponseField name="tag" type="string">
+  A tag that appears next to your page title in the sidebar.
+</ResponseField>
 
-```mdx
+```yaml Example YAML frontmatter wrap
 ---
-title: "Your very long page title you want to shorten"
-sidebarTitle: "Short title"
+title: "About frontmatter"
+description: "Frontmatter is the metadata that controls how your page appears and behaves"
+sidebarTitle: "Frontmatter"
+icon: "book"
+tag: "NEW"
 ---
 ```
 
-## Icons
-
-Add an icon next to your page's sidebar title by including the `icon` field in your page's frontmatter.
+## Page mode
 
-```mdx
----
-title: "Code Block"
-icon: "code"
----
-```
+Control how your page displays with the `mode` setting.
 
-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).
+### Default
 
-For Font Awesome icons, you can optionally set the icon type. If not set, the icon type will be regular.
+If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents.
 
-```mdx
+```yaml
 ---
-iconType: "solid"
+title: "Default page title"
 ---
 ```
 
-## Tag
+### Wide
 
-Add tags to label specific pages. Tags display in the sidebar next to page titles.
+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
----
-tag: "NEW"
+```yaml
 ---
-```
-
-## 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.
-
-Learn more about API pages by visiting the [API page guides](/api-playground/overview).
-
-```mdx
----
-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.
-
-### Default
+### Custom
 
-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
+Learn more about building [API documentation](/api-playground/overview).
 
-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.
+## External links
 
-```mdx
----
-mode: "center"
----
-```
-
-## External Links
+Link to external sites directly from your navigation with the `url` metadata.
 
-If you want the sidebar to open an external URL, you can set the `url` metadata
-in any page.
-
-```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.
+<Note>
+  Meta tags with colons must be wrapped in quotes.
+</Note>
 
-```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']
 ---
-```
+```