mintlify · mintlify · Dec 18, 2025 · Dec 18, 2025 · Dec 18, 2025 · Dec 18, 2025
diff --git a/api-playground/adding-sdk-examples.mdx b/api-playground/adding-sdk-examples.mdx
@@ -6,7 +6,9 @@
 
 If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages.
 
+SDK examples appear alongside the default cURL examples in your API playground, making it easier for developers to integrate with your API using their preferred language or framework.
+
 This property can be added to any request method and has the following schema.
 
 <ParamField body="lang" type="string" required>
  The language of the code sample.
@@ -20,7 +22,7 @@
  The source code of the sample.
 </ParamField>

 Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.

 ```yaml
 paths:
@@ -48,3 +50,96 @@
             planter.list({ potted: true });
 ```
 
+## Multiple SDK languages
+
+You can provide examples in multiple programming languages to support different developer audiences. Common languages include:
+
+<CodeGroup>
+
+```yaml Python example
+x-codeSamples:
+  - lang: python
+    label: Get user by ID
+    source: |
+      import requests
+
+      response = requests.get(
+          'https://api.example.com/users/123',
+          headers={'Authorization': 'Bearer YOUR_TOKEN'}
+      )
+      user = response.json()
+```
+
+```yaml JavaScript example
+x-codeSamples:
+  - lang: javascript
+    label: Get user by ID
+    source: |
+      const response = await fetch('https://api.example.com/users/123', {
+        headers: {
+          'Authorization': 'Bearer YOUR_TOKEN'
+        }
+      });
+      const user = await response.json();
+```
+
+```yaml Go example
+x-codeSamples:
+  - lang: go
+    label: Get user by ID
+    source: |
+      client := &http.Client{}
+      req, _ := http.NewRequest("GET", "https://api.example.com/users/123", nil)
+      req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
+      resp, _ := client.Do(req)
+```
+
+```yaml Ruby example
+x-codeSamples:
+  - lang: ruby
+    label: Get user by ID
+    source: |
+      require 'net/http'
+      require 'json'
+
+      uri = URI('https://api.example.com/users/123')
+      req = Net::HTTP::Get.new(uri)
+      req['Authorization'] = 'Bearer YOUR_TOKEN'
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
+      end
+      user = JSON.parse(response.body)
+```
+
+</CodeGroup>
+
+## Best practices
+
+<AccordionGroup>
+  <Accordion title="Use realistic examples">
+    Provide examples that reflect actual use cases rather than placeholder code. Include error handling and common patterns your users will need.
+  </Accordion>
+
+  <Accordion title="Keep examples concise">
+    Focus on the essential code needed to make the API call. Avoid unnecessary boilerplate that distracts from the core functionality.
+  </Accordion>
+
+  <Accordion title="Match your SDK">
+    If you provide official SDKs, ensure the examples match your SDK's actual API and conventions. Keep examples updated when your SDK changes.
+  </Accordion>
+
+  <Accordion title="Include authentication">
+    Show how to properly authenticate requests in each language, as authentication patterns vary significantly across SDKs.
+  </Accordion>
+
+  <Accordion title="Add helpful labels">
+    Use descriptive labels when providing multiple examples for the same endpoint to help users find the right example quickly.
+  </Accordion>
+</AccordionGroup>
+
+## Related resources
+
+<Card title="Learn more about OpenAPI setup" icon="code" href="/api-playground/openapi-setup">
+  Configure OpenAPI specifications and generate API documentation
+</Card>
+
diff --git a/create/code.mdx b/create/code.mdx
@@ -8,6 +8,10 @@
 
 You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more.
 
+<Card title="Learn more about text formatting" icon="text" href="/create/text">
+  Format text, create headers, and style content
+</Card>
+
 ### Inline code
 
 To denote a `word` or `phrase` as code, enclose it in backticks (\`).
@@ -146,7 +150,7 @@

 </Accordion>

 ### Twoslash

 In JavaScript and TypeScript code blocks, use `twoslash` to enable interactive type information. Users can hover over variables, functions, and parameters to see types and errors like in an IDE.


diff --git a/create/text.mdx b/create/text.mdx
@@ -8,6 +8,10 @@
 
 Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation.
 
+<Card title="Learn more about code formatting" icon="code" href="/create/code">
+  Display and style inline code and code blocks
+</Card>
+
 ### Creating headers
 
 Use `#` symbols to create headers of different levels:
@@ -24,7 +28,7 @@

 ### Disabling anchor links

 By default, headers include clickable anchor links that allow users to link directly to specific sections. You can disable these anchor links using the `noAnchor` prop in HTML or React headers.

 <CodeGroup>

@@ -42,11 +46,11 @@

 </CodeGroup>

 When `noAnchor` is used, the header will not display the anchor chip and clicking the header text will not copy the anchor link to the clipboard.

 ## Text formatting

 We support most Markdown formatting for emphasizing and styling text.

 ### Basic formatting

@@ -120,7 +124,7 @@

 Blockquotes highlight important information, quotes, or examples within your content.

 ### Single line blockquotes

 Add `>` before text to create a blockquote:

@@ -130,7 +134,7 @@

 > This is a quote that stands out from the main content.

 ### Multi-line blockquotes

 For longer quotes or multiple paragraphs:

@@ -150,14 +154,14 @@

 ## Mathematical expressions

 We support LaTeX for rendering mathematical expressions and equations. You can override automated detection by configuring `styles.latex` in your `docs.json` [settings](/organize/settings#param-latex).

 ### Inline math

 Use single dollar signs, `$`, for inline mathematical expressions:

 ```mdx
 The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
 ```

 The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
@@ -218,7 +222,7 @@

 ### Content organization
 - Use headers to create clear content hierarchy
 - Follow proper header hierarchy (don't skip from H2 to H4)
 - Write descriptive, keyword-rich header text

 ### Text formatting

diff --git a/deploy/ci.mdx b/deploy/ci.mdx
@@ -10,12 +10,16 @@
 
 Use CI checks to lint your docs for errors and provide warnings before you deploy. Mintlify CI checks run on pull requests against a configured deployment branch.
 
+<Card title="Learn more about GitHub deployments" icon="github" href="/deploy/github">
+  Connect to a GitHub repository for automated deployments and pull request previews
+</Card>
+
 ## Installation
 
 To begin, follow the steps on the [GitHub](/deploy/github) page.

 <Tip>
  Only access to the repository where your documentation content exists is required, so it is highly recommended to only grant access to that repository. 
 </Tip>

 ## Configuration
@@ -24,8 +28,8 @@

 When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.

 - A `Warning` level check will never provide a failure status, even if there is an error or suggestions.
 - A `Blocking` level check will provide a failure status if there is an error or suggestions.

 ## Available CI checks

@@ -355,8 +359,8 @@

 To add your own vocabulary for the default configuration, create a `styles/config/vocabularies/Mintlify` directory with `accept.txt` and `reject.txt` files.

 - `accept.txt`: Words that should be ignored by the Vale linter. For example, product names or uncommon terms.
 - `reject.txt`: Words that should be flagged as errors. For example, jargon or words that are not appropriate for the tone of your documentation.

 ```text Example Vale file structure
 /your-project
@@ -394,12 +398,12 @@
 </Note>

 #### Packages
 Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration.

 For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they're automatically downloaded and used in your Vale configuration.

 <Note>
 For security reasons, automatically downloading packages that aren't from the [Vale package registry](https://vale.sh/explorer) is **not** supported.
 </Note>

 #### Vale with `MDX`
@@ -413,9 +417,9 @@
 ```mdx
 {/* vale off */}

 This text is ignored by Vale

 {/* vale on */}
 ```

 Vale automatically recognizes and respects these comments in MDX files without additional configuration. Use comments to skip lines or sections that should be ignored by the linter.
diff --git a/deploy/github.mdx b/deploy/github.mdx
@@ -15,9 +15,13 @@
   See your repository in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard.
 </Tip>
 
+<Card title="Learn more about CI deployments" icon="gears" href="/deploy/ci">
+  Deploy from CI/CD pipelines with GitHub Actions, GitLab CI, and more
+</Card>
+
 If your repository is in the `mintlify-community` organization, the GitHub App is automatically configured and managed by Mintlify. You can use the web editor to make changes to your documentation. If you want to work on your documentation locally, clone the repository to your own organization and update your Git settings to use your own repository.
 
 ## Install the GitHub App

 <Note>
  You must have organization ownership or administrator permissions in a repository to install the app. If you lack the necessary permissions, the repository owner must approve the installation request.
@@ -26,7 +30,7 @@
 Install the Mintlify GitHub App through your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app).

 <Tip>
  We recommend only granting access to your documentation repository.
 </Tip>

 <Frame>
@@ -52,15 +56,15 @@

 ## Manage repository access

 When installing the GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to your documentation repository and any repositories that you want to provide as context for the agent. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new).

 ## Configure docs source

 Change the organization, repository, or branch that your documentation builds from in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) section of your dashboard.

 ## GitHub Enterprise with IP allowlists

 If your GitHub Enterprise Cloud organization has an IP allowlist enabled, you need to add Mintlify's egress IP address (`54.242.90.151`) to your allowlist for the GitHub App to function properly.

 Follow [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) to configure your IP allowlist.

@@ -84,7 +88,7 @@
  </Accordion>
 </AccordionGroup>

 ### GitHub App connection issues

 If you encounter problems with the GitHub app, resetting the connection can solve most problems.

@@ -101,7 +105,7 @@

 ### Feedback add-ons are unavailable

 If you cannot enable the edit suggestions or raise issues options in your dashboard and your repository is public, revalidate your Git settings.

 <Steps>
  <Step title="Navigate to Git Settings">

diff --git a/docs.json b/docs.json
@@ -228,7 +228,8 @@
                 "group": "Overview",
                 "icon": "book-open",
                 "pages": [
-                  "guides/index"
+                  "guides/index",
+                  "guides/common-tasks"
                 ]
               },
               {

diff --git a/guides/common-tasks.mdx b/guides/common-tasks.mdx
@@ -0,0 +1,177 @@
+---
+title: "Common tasks"
+description: "Quick reference for frequently performed documentation tasks."
+keywords: ["quick reference", "common tasks", "how-to", "getting started"]
+---
+
+This page provides quick links to common documentation tasks. Use this as a starting point to find the information you need quickly.
+
+## Getting started
+
+<CardGroup cols={2}>
+  <Card title="Create your first page" icon="file-plus" href="/quickstart">
+    Set up your documentation and create your first page
+  </Card>
+  <Card title="Install the CLI" icon="terminal" href="/installation">
+    Install the Mintlify CLI for local development
+  </Card>
+  <Card title="Choose a theme" icon="palette" href="/customize/themes">
+    Select and customize your documentation theme
+  </Card>
+  <Card title="Configure navigation" icon="sitemap" href="/organize/navigation">
+    Set up your documentation structure and navigation
+  </Card>
+</CardGroup>
+
+## Content creation
+
+<CardGroup cols={2}>
+  <Card title="Format text" icon="text" href="/create/text">
+    Learn Markdown formatting, headers, and links
+  </Card>
+  <Card title="Add code blocks" icon="code" href="/create/code">
+    Display code with syntax highlighting and options
+  </Card>
+  <Card title="Use components" icon="puzzle-piece" href="/components/accordions">
+    Add interactive components like accordions and tabs
+  </Card>
+  <Card title="Add callouts" icon="message-exclamation" href="/components/callouts">
+    Highlight important information with callouts
+  </Card>
+</CardGroup>
+
+## Organization
+
+<CardGroup cols={2}>
+  <Card title="Configure page metadata" icon="file-lines" href="/organize/pages">
+    Set titles, descriptions, and frontmatter
+  </Card>
+  <Card title="Organize with groups" icon="folder" href="/organize/navigation#groups">
+    Structure content with navigation groups
+  </Card>
+  <Card title="Add tabs" icon="window-restore" href="/organize/navigation#tabs">
+    Create separate documentation sections with tabs
+  </Card>
+  <Card title="Configure settings" icon="gear" href="/organize/settings">
+    Customize global documentation settings
+  </Card>
+</CardGroup>
+
+## API documentation
+
+<CardGroup cols={2}>
+  <Card title="Set up OpenAPI" icon="square-terminal" href="/api-playground/openapi-setup">
+    Generate API docs from OpenAPI specifications
+  </Card>
+  <Card title="Create API pages" icon="code" href="/api-playground/overview">
+    Build interactive API playgrounds
+  </Card>
+  <Card title="Configure authentication" icon="lock" href="/api-playground/authentication">
+    Set up API authentication methods
+  </Card>
+  <Card title="Add MDX content" icon="file-code" href="/api-playground/mdx">
+    Enhance API pages with custom content
+  </Card>
+</CardGroup>
+
+## Customization
+
+<CardGroup cols={2}>
+  <Card title="Customize colors" icon="palette" href="/organize/settings#param-colors">
+    Set your brand colors and theme
+  </Card>
+  <Card title="Add custom domain" icon="globe" href="/organize/settings#param-domain">
+    Configure a custom domain for your docs
+  </Card>
+  <Card title="Configure footer" icon="rectangle-vertical" href="/organize/settings#param-footer">
+    Customize footer links and content
+  </Card>
+  <Card title="Add analytics" icon="chart-line" href="/integrations/analytics/overview">
+    Track documentation usage with analytics
+  </Card>
+</CardGroup>
+
+## Deployment
+
+<CardGroup cols={2}>
+  <Card title="Deploy with GitHub" icon="github" href="/deploy/github">
+    Connect GitHub for automated deployments
+  </Card>
+  <Card title="Set up CI checks" icon="gears" href="/deploy/ci">
+    Automate linting and validation in CI/CD
+  </Card>
+  <Card title="Preview changes" icon="eye" href="/deploy/github#install-the-github-app">
+    Generate preview deployments for pull requests
+  </Card>
+  <Card title="Configure custom domain" icon="link" href="/organize/settings#param-domain">
+    Set up a custom domain for your documentation
+  </Card>
+</CardGroup>
+
+## Optimization
+
+<CardGroup cols={2}>
+  <Card title="Improve SEO" icon="magnifying-glass" href="/optimize/seo">
+    Optimize for search engines and social sharing
+  </Card>
+  <Card title="Add search keywords" icon="key" href="/organize/pages#internal-search-keywords">
+    Enhance page discoverability in search
+  </Card>
+  <Card title="Check broken links" icon="link-slash" href="/installation#find-broken-links">
+    Find and fix broken links in your docs
+  </Card>
+  <Card title="Configure redirects" icon="arrow-right-arrow-left" href="/organize/settings#param-redirects">
+    Set up URL redirects for moved content
+  </Card>
+</CardGroup>
+
+## Integrations
+
+<CardGroup cols={2}>
+  <Card title="Add analytics" icon="chart-simple" href="/integrations/analytics/overview">
+    Integrate Google Analytics, Mixpanel, and more
+  </Card>
+  <Card title="Enable feedback" icon="comment" href="/organize/settings#param-feedback">
+    Collect user feedback on documentation pages
+  </Card>
+  <Card title="Configure search" icon="magnifying-glass" href="/organize/settings#param-search">
+    Customize search functionality
+  </Card>
+  <Card title="Add chat support" icon="messages" href="/organize/settings#param-chat">
+    Integrate chat support widgets
+  </Card>
+</CardGroup>
+
+## Troubleshooting
+
+<CardGroup cols={2}>
+  <Card title="Fix deployment issues" icon="triangle-exclamation" href="/deploy/github#troubleshooting">
+    Resolve common GitHub deployment problems
+  </Card>
+  <Card title="Check broken links" icon="link-slash" href="/create/text#broken-links">
+    Use the CLI to find broken links
+  </Card>
+  <Card title="Validate configuration" icon="check" href="/organize/settings">
+    Ensure your docs.json is properly configured
+  </Card>
+  <Card title="Debug navigation" icon="sitemap" href="/organize/navigation">
+    Fix navigation structure issues
+  </Card>
+</CardGroup>
+
+## Need more help?
+
+<CardGroup cols={2}>
+  <Card title="Browse all guides" icon="book" href="/guides/improving-docs">
+    Explore comprehensive documentation guides
+  </Card>
+  <Card title="View all components" icon="puzzle-piece" href="/components/accordions">
+    See all available documentation components
+  </Card>
+  <Card title="Check settings reference" icon="gear" href="/organize/settings">
+    Review all configuration options
+  </Card>
+  <Card title="Contact support" icon="life-ring" href="https://mintlify.com/support">
+    Get help from the Mintlify team
+  </Card>
+</CardGroup>
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
@@ -14,6 +14,10 @@
 
 Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.
 
+<Card title="Learn more about pages" icon="file" href="/organize/pages">
+  Configure page metadata, titles, and frontmatter properties
+</Card>
+
 <img
   className="block dark:hidden pointer-events-none"
   src="/images/navigation/pages-light.png"
@@ -98,11 +102,11 @@

 Use the `expanded` property to control the default state of a nested group in the navigation sidebar.

 - `expanded: true`: Group is expanded by default.
 - `expanded: false` or omitted: Group is collapsed by default.

 <Note>
  The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.
 </Note>

 ```json
@@ -271,7 +275,7 @@
 Use global anchors for external links that should appear on all pages, regardless of which section of your navigation the user is viewing. Global anchors are particularly useful for linking to resources outside your documentation, such as a blog, community forum, or support portal.

 <Note>
  Global anchors must include an `href` field pointing to an external URL. They cannot contain relative paths.
 </Note>

 ```json
@@ -298,7 +302,7 @@

 ## Dropdowns

 Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.

 <img
  className="block dark:hidden pointer-events-none"
@@ -413,15 +417,17 @@

 Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.

 Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.

 <Note>
  When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification.

   To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
 </Note>
 
-For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
+<Card title="Learn more about OpenAPI" icon="code" href="/api-playground/openapi-setup">
+  Set up OpenAPI specifications and generate API documentation
+</Card>
 
 ```json
 {
@@ -513,7 +519,7 @@

 In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.

 We currently support the following languages for localization:

 <CardGroup cols={2}>
  <Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
@@ -572,9 +578,9 @@

 ## Nesting

 Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.

 Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.

 <CodeGroup>

@@ -796,7 +802,7 @@

 ## Breadcrumbs

 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the `styling` property in your `docs.json`.

 <CodeGroup>

@@ -820,10 +826,10 @@

 ### Enable auto-navigation for groups

 When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.

 - Set to `true` to force automatic navigation to the first page when a navigation group is selected.
 - Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
 - Leave unset to use the theme's default behavior.

 <CodeGroup>

diff --git a/organize/pages.mdx b/organize/pages.mdx
@@ -4,7 +4,7 @@
 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.

 ## Page metadata

@@ -15,15 +15,19 @@
 - Page titles and descriptions
 - Sidebar titles, icons, and tags
 - Page layouts
 - SEO meta tags
 - Custom metadata
 
+<Card title="Learn more about navigation" icon="sitemap" href="/organize/navigation">
+  Design information architecture and configure navigation structure
+</Card>
+
 <ResponseField name="title" type="string" required>
   The title of your page that appears in navigation and browser tabs.
 </ResponseField>

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

 <ResponseField name="sidebarTitle" type="string">
@@ -70,7 +74,7 @@

 ### Default

 If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents.

 ```yaml
 ---
@@ -80,7 +84,7 @@

 ### 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.

 ```yaml
 ---
@@ -132,7 +136,9 @@
 ---
 ```
 
-Learn more about building [API documentation](/api-playground/overview).
+<Card title="Learn more about API documentation" icon="square-terminal" href="/api-playground/overview">
+  Build interactive API playgrounds and reference documentation
+</Card>
 
 ## External links
 
@@ -147,10 +153,10 @@

 ## 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.

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

 ```yaml
@@ -159,11 +165,13 @@
 ---
 ```
 
-See [SEO](/optimize/seo) for complete SEO metadata options.
+<Card title="Learn more about SEO" icon="magnifying-glass" href="/optimize/seo">
+  Optimize your documentation for search engines and social sharing
+</Card>
 
 ## 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.

 ```yaml
 ---