diff --git a/pages.mdx b/pages.mdx
index fa53544d..242f9f5e 100644
--- a/pages.mdx
+++ b/pages.mdx
@@ -4,170 +4,135 @@ 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"
----
-```
+
+ The title of your page that appears in navigation and browser tabs.
+
-## Descriptions
+
+ A brief description of what this page covers. Appears under the title and improves SEO.
+
-You can add a description that shows the summary of the page under the title with the `description` metadata.
+
+ A short title that displays in the sidebar navigation.
+
-```mdx
----
-description: "Your description goes here"
----
-```
+
+ 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
+
-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.
+
+ A tag that appears next to your page title in the sidebar.
+
-```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.
+
+ 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
+```