From ca14090fa81cc920731dd170a50c14434a7e1bba Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 10 Mar 2025 19:07:29 +0000
Subject: [PATCH] Documentation edits made through Mintlify web editor
---
api-playground/openapi/setup.mdx | 257 +++--
docs.json | 19 +-
quickstart.mdx | 267 +++---
settings/global.mdx | 1544 +++---------------------------
text.mdx | 126 ++-
5 files changed, 510 insertions(+), 1703 deletions(-)
diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx
index 93b47c02..93221087 100644
--- a/api-playground/openapi/setup.mdx
+++ b/api-playground/openapi/setup.mdx
@@ -3,157 +3,156 @@ title: "OpenAPI Setup"
description: "Reference OpenAPI endpoints in your docs pages"
---
-## Add an OpenAPI specification file
+## Getting Started with OpenAPI Integration
-To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
-document in either JSON or YAML format that follows the
-[OpenAPI specification](https://swagger.io/specification/). Your document must
-follow OpenAPI specification 3.0+.
-To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command:
`mintlify openapi-check `
+### Prerequisites
+Before integrating OpenAPI into your documentation, ensure you have:
-## Auto-populate API pages
+- A valid OpenAPI document (JSON or YAML format)
+- OpenAPI specification 3.0 or higher
+- [Mintlify CLI](https://www.npmjs.com/package/mintlify) installed
-The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab.
+
+ Validate your OpenAPI specification using our CLI:
+ ```bash
+ mintlify openapi-check
+ ```
+
+
+## Implementation Methods
+
+### Method 1: Auto-population with Navigation Tabs
+The quickest way to implement OpenAPI is through your `docs.json` configuration. You can either reference a local file or a hosted URL.
-**Example with Tabs:**
-```json {5}
-"navigation": {
- "tabs": [
- {
+
+```json Tab-Based Navigation
+{
+ "navigation": {
+ "tabs": [
+ {
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
- }
- ]
+ }
+ ]
+ }
}
```
-
-
-**Example with Groups:**
-```json {8-11}
-"navigation": {
- "tabs": [
- {
- "tab": "API Reference",
- "groups": [
- {
- "group": "Endpoints",
- "openapi": {
- "source": "/path/to/openapi-1.json",
- "directory": "api-reference"
+
+```json Group-Based Navigation
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "API Reference",
+ "groups": [
+ {
+ "group": "Endpoints",
+ "openapi": {
+ "source": "/path/to/openapi-1.json",
+ "directory": "api-reference"
+ }
}
- }
- ]
- }
- ]
+ ]
+ }
+ ]
+ }
}
```
-
-When using this option, the metadata for the generated pages will have the following default values:
-
-* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
-
-* `description`: The `description` field from the OpenAPI operation, if present.
-
-* `version`: The `version` value from the anchor or tab, if present.
-
-There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.
-
-## Create MDX files for API pages
-
-If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases).
-
-
-
-### Manually specify files
-
-You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
-
-
-
-By using the OpenAPI reference, the name, description, parameters, responses,
-and the API playground will be automatically generated from the OpenAPI document.
-
-If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have
-only one OpenAPI file - it will automatically detect your OpenAPI file.
-
-
- ```md Example
- ---
- title: "Get users"
- openapi: "/path/to/openapi-1.json GET /users"
- ---
- ```
-
- ```md Format
- ---
- title: "title of the page"
- openapi: openapi-file-path method path
- ---
- ```
-
+
+ Auto-generated pages will use the following metadata by default:
+ - **Title**: OpenAPI operation summary or generated from HTTP method/endpoint
+ - **Description**: OpenAPI operation description
+ - **Version**: Version value from the anchor/tab (if present)
+
+
+### Method 2: Custom MDX Pages
+
+For more control over your API documentation, you can create individual MDX pages for each operation.
+
+
+
+ Create a new MDX file for your API endpoint. Here's an example structure:
+ ```md
+ ---
+ title: "Get users"
+ openapi: "/path/to/openapi-1.json GET /users"
+ ---
+ ```
+
+
+
+ The `openapi` field format should follow:
+ ```
+ openapi:
+ ```
+
+
+ If you only have one OpenAPI file, the file path is optional - Mintlify will automatically detect it.
+
+
+
+
+ Add any additional content or customization below the frontmatter.
+
+
+
+
+ The method and path must exactly match those in your OpenAPI document. For webhooks, use "webhook" instead of the HTTP method (e.g., "POST").
+
+
+### Method 3: Automated File Generation
+
+For large OpenAPI documents, use our scraping tool to automatically generate MDX files.
+
+
+
+ Use our [@mintlify/scraping](https://www.npmjs.com/package/@mintlify/scraping) package:
+ ```bash
+ npx @mintlify/scraping@latest openapi-file
+ ```
+
+
+
+ Add the `-o` flag to choose where files are generated:
+ ```bash
+ npx @mintlify/scraping@latest openapi-file -o api-reference
+ ```
+
+
+
+ Add the generated navigation entries to your configuration:
+ - Append them to existing navigation, or
+ - Manually organize them in your preferred structure
+
+
- In most cases, the method and path must match the method and path specified
- in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI
- file, the page will be empty.
-
- For webhooks, replace the method (i.e. "POST") with "webhook" (case insensitive)
- and the correct method will be generated.
+ The scraper requires a valid OpenAPI document. Invalid specifications will not generate files.
-### Autogenerate files
-
-For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.
-
-Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping)
-autogenerates MDX files for your OpenAPI endpoints.
+## Working with OpenAPI Schemas
-Each generated page will correspond to an OpenAPI operation under the "paths" section of the OpenAPI schema.
-If your OpenAPI document is version 3.1+, the scraper will also generate pages for webhooks under the "webhooks" section of the OpenAPI schema.
+### Individual Schema Pages
+Create dedicated pages for schemas defined in your OpenAPI document's `components.schemas`:
-```bash
-npx @mintlify/scraping@latest openapi-file
+
+```md Example
+---
+openapi-schema: OrderItem
+---
```
-Add the `-o` flag to specify a folder to populate the files into. If a folder is
-not specified, the files will populate in the working directory.
-
-```bash
-npx @mintlify/scraping@latest openapi-file -o api-reference
+```md Format
+---
+openapi-schema: "schema-key"
+---
```
+
-Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
-
-The scraper will output an array of
-[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
-files. You can either append these entries to your existing Navigation, or
-reorder and add the files to your navigation manually.
-
-
- If your OpenAPI document is invalid, the files will not autogenerate.
-
-
-
-
-## Create MDX files for OpenAPI schemas
-
-Mintlify also allows you to create individual pages for any OpenAPI schema
-defined in an OpenAPI document's `components.schemas` field:
-
-
- ```md Example
- ---
- openapi-schema: OrderItem
- ---
- ```
-
- ```md Format
- ---
- openapi-schema: "schema-key"
- ---
- ```
-
\ No newline at end of file
+
+ Schema pages automatically inherit documentation from your OpenAPI specification while allowing you to add custom content and examples.
+
\ No newline at end of file
diff --git a/docs.json b/docs.json
index 6ee7d5d0..ca9803bc 100644
--- a/docs.json
+++ b/docs.json
@@ -22,7 +22,11 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
- "pages": ["development", "web-editor"]
+ "pages": [
+ "development",
+ "web-editor",
+ "quickstart"
+ ]
},
"settings/global",
{
@@ -37,7 +41,9 @@
]
},
"themes",
- "migration"
+ "migration",
+ "text",
+ "settings/global"
]
},
{
@@ -61,7 +67,8 @@
"pages": [
"api-playground/openapi/setup",
"api-playground/openapi/writing-openapi",
- "api-playground/openapi/advanced-features"
+ "api-playground/openapi/advanced-features",
+ "api-playground/openapi/setup"
]
},
{
@@ -263,7 +270,9 @@
"groups": [
{
"group": "Changelog",
- "pages": ["changelog/overview"]
+ "pages": [
+ "changelog/overview"
+ ]
}
]
}
@@ -375,4 +384,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
-}
+}
\ No newline at end of file
diff --git a/quickstart.mdx b/quickstart.mdx
index bc95e693..20e422eb 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -15,172 +15,205 @@ icon: "rocket"
/>
-## Getting Started
+## Overview
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
+Welcome to Mintlify! This guide will walk you through the essential steps to create, deploy, and customize your documentation. Follow these instructions to get your docs up and running in minutes.
-### Creating the Repository
+## Initial Setup
-Mintlify docs are rendered from MDX files and configurations defined in our
-[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
-your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
+### Setting Up Your Repository
-
+
+
+ You have two options to get started:
+ - Use our [dashboard](https://dashboard.mintlify.com) for guided setup
+ - Clone our [starter kit](https://github.com/mintlify/starter) directly
+
-
-
- Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
+
+
+ The GitHub app ensures automatic deployment of your documentation updates.
+
+
+ 1. Go to [dashboard settings](https://dashboard.mintlify.com/settings)
+ 2. Find the GitHub app installation link
+ 3. Complete the installation process
+ 4. Verify successful integration (look for the checkmark next to your commit hash)
- 
+ 
+
+
-
-
-
- If you want your docs to live alongside your code as a monorepo setup, you
- can: 1. Move your docs content to your monorepo. 2. Specify the path to your
- `docs.json` in the
- [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
-
- 
- 
-
-
-
-
-
-### Updating the Content
+### Monorepo Configuration
-Mintlify enables you to easily customize the style, structure, and content of
-your docs.
+
+ If you prefer keeping your docs alongside your code, Mintlify supports monorepo setups.
+
-
-
-
- 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
- 3. Use your favorite IDE to open the repository.
- 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.
-
- Learn more about this in our [local development guide](/development).
-
-
+
+
+ Transfer your docs content into your monorepo structure
+
+
+
+ Specify your `docs.json` path in the [dashboard settings](https://dashboard.mintlify.com/settings/deployment/git-settings)
+
+
-
+
+
+
+
- Learn more about how to use the web editor on our [guide](/web-editor).
+## Content Management
-
+### Local Development Setup
-
-
- Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations:
+
+
+ 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+ 2. Set up [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for GitHub
+
- ```json
- "name": "Your Company"
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg",
- "href": "https://yourcompany.com"
- },
- "favicon": "/favicon.svg",
- "colors": {
- "primary": "#2AB673",
- "light": "#55D799",
- "dark": "#117866",
- },
- ```
+
+ 1. Clone your repository: `git clone `
+ 2. Open the repository in your preferred IDE
+ 3. Install Mintlify CLI: `npm i -g mintlify`
+
+
- A full list of supported configurations can be found at [global settings](/settings/global).
+
+ For detailed instructions on local development, check our [development guide](/development).
+
-
+### Web Editor
-
+For those who prefer a browser-based editing experience, we offer a powerful web editor. Learn more in our [web editor guide](/web-editor).
- Add content with simple MDX files. Initiate your pages with this template:
+### Brand Customization
- ```md
- ---
- title: "Page Title"
- sidebarTitle: "Sidebar title (optional - if different from page title)"
- description: "Subtitle (optional)"
- ---
- ```
+Customize your documentation's appearance through the `docs.json` configuration file:
- Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
+```json
+{
+ "name": "Your Company",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg",
+ "href": "https://yourcompany.com"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#2AB673",
+ "light": "#55D799",
+ "dark": "#117866"
+ }
+}
+```
-
+
+ Find all available configuration options in our [global settings](/settings/global) guide.
+
-
+### Creating Content
- Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
+Add new pages using MDX files with this basic structure:
-
- 
-
+```md
+---
+title: "Page Title"
+sidebarTitle: "Sidebar title (optional)"
+description: "Subtitle (optional)"
+---
+```
-
+
+ Explore our guides on [MDX syntax](/text) and [components](/content/components) to enhance your content.
+
-
+## API Documentation
- You can easily set up your API references using an OpenAPI document.
+### Setting Up API References
- 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL.
+
+
+ Add your OpenAPI specification file (`openapi.yaml` or `openapi.json`) to your repository, or specify a URL in `docs.json`:
```json
- "openapi": "link-to-your-openapi-file"
+ {
+ "openapi": "link-to-your-openapi-file"
+ }
```
+
- 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
-
+
+ Use our scraper to create endpoint files:
```bash
npx @mintlify/scraping@latest openapi-file
```
+
- 3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`.
+
+ Include the generated MDX files in your `docs.json` navigation structure
+
+
- For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview).
+
+ For detailed API documentation setup, see our guides on [OpenAPI setup](/api-playground/openapi/setup) and [authentication](/api-playground/openapi/writing-openapi).
+
-
+## Analytics and Tracking
-
+Monitor your documentation's performance through:
+- Built-in analytics dashboard
+- Page view tracking
+- Search analytics
+- Session recordings
- Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
-
- We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
-
-
-
+Access these features in your [dashboard](https://dashboard.mintlify.com/analytics).
- We provide a white-glove migration service as part of our Enterprise plan.
- Interested? You can request it by [contacting us](mailto:sales@mintlify.com).
+ We support various third-party analytics integrations. See our [analytics integrations guide](/integrations/analytics/overview).
-### Publishing
+## Domain Configuration
+
+### Custom Domain Setup
+
+
+
+ Navigate to [dashboard settings](https://dashboard.mintlify.com/settings)
+
-
+
+ Configure your custom domain in the domains section
+
+
-Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
+
+ 
+
-Navigate to your [dashboard settings](https://dashboard.mintlify.com/settings) to add a custom domain.
+
+ Ensure your DNS settings are properly configured after adding your custom domain.
+
-
+## Additional Support
-
+
+ Enterprise customers can access our white-glove migration service. Contact [sales@mintlify.com](mailto:sales@mintlify.com) for details.
+
-Congrats! You've set up your Mintlify Docs and it's looking amazing! Need
-support or want to give some feedback? You can join our
-[community](https://mintlify.com/community) or drop us an email at
-[support@mintlify.com](mailto:support@mintlify.com).
+Need help or want to provide feedback?
+- Join our [community](https://mintlify.com/community)
+- Email us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file
diff --git a/settings/global.mdx b/settings/global.mdx
index a85b9972..039f4550 100644
--- a/settings/global.mdx
+++ b/settings/global.mdx
@@ -6,31 +6,51 @@ icon: "wrench"
import ConfigUpgrade from "/snippets/config-upgrade.mdx";
-Every documentation site requires a `docs.json` file that contains the core configuration settings. This file controls everything from styling and navigation to integrations and analytics.
+# Global Documentation Configuration
+
+Every documentation site requires a `docs.json` file that contains the core configuration settings. This file is the central control point for everything from styling and navigation to integrations and analytics.
-## Properties
+
+ Make sure to place your `docs.json` file in the root directory of your documentation project.
+
-### Customization
+## Core Properties
-
- The layout theme of the project. Examples:
- [Maple](https://maple.mintlify.app/), [Palm](https://palm.mintlify.app/),
-
+These fundamental settings define your documentation's identity and basic configuration.
+
+### Project Information
- The name of the project, organization, or product Minimum length: 1
+ The name of your project, organization, or product. This appears in various places throughout your documentation.
+
+ Minimum length: 1 character
- Optional description used for SEO and LLM indexing
+ A brief description of your documentation site. This is used for SEO purposes and LLM indexing to help users find your content.
-### Styling
+### Theme Selection
+
+
+ Choose the layout theme for your project. Each theme provides a unique look and feel:
+
+ - **Mint**: Our default modern theme
+ - **[Maple](https://maple.mintlify.app/)**: Clean and minimalist
+ - **[Palm](https://palm.mintlify.app/)**: Bold and engaging
+
+
+## Visual Customization
+
+Configure the visual elements of your documentation to match your brand.
+
+### Brand Colors
- The colors to use in your documentation. At the very least, you must define the primary color. For example:
+ Define your documentation's color scheme. At minimum, specify the primary color:
+
```json
{
"colors": {
@@ -39,1510 +59,216 @@ Every documentation site requires a `docs.json` file that contains the core conf
}
```
-
+
- The primary color of the theme
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
+ The primary brand color used throughout the theme
- The light color of the theme. Used for dark mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
+ A lighter variant for dark mode contrast
- The dark color of the theme. Used for light mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
+ A darker variant for light mode contrast
+### Logo Configuration
+
- The logo (for both light and dark mode)
+ Set your documentation's logo. You can either use a single logo or specify different versions for light and dark modes.
-
+
- Path pointing to the light logo file to use in dark mode, including the file extension. Example: `/logo.png`
+ Path to the logo for light mode (e.g., `/logo.svg`)
- Path pointing to the dark logo file to use in light mode, including the file extension. Example: `/logo-dark.png`
+ Path to the logo for dark mode (e.g., `/logo-dark.svg`)
- The URL to redirect to when clicking the logo. If not provided, the logo will link to the homepage. Example: `https://example.com`
+ Custom URL for logo clicks (defaults to homepage)
+### Favicon Settings
+
- The path to your favicon file in the docs folder, including the file extension. The file will automatically be resized to appropriate favicon sizes.
- Can be a single file or a pair for light and dark mode. Example: `/favicon.png`
+ Configure your site's favicon. The file will be automatically resized to appropriate favicon sizes.
-
+
- Path pointing to the light favicon file to use in dark mode, including the file extension. Example: `/favicon.png`
+ Light mode favicon path
- Path pointing to the dark favicon file to use in light mode, including the file extension. Example: `/favicon-dark.png`
+ Dark mode favicon path
-
- Styling configurations
-
-
-
- The eyebrows style of the content. Defaults to `section`.
-
-
- The codeblock theme. Defaults to `system`.
-
-
-
-
-
- Icon library settings
-
-
-
- The icon library to be used. Defaults to `fontawesome`.
-
-
-
+## Typography & Fonts
+ Customize the typography of your documentation with custom fonts.
-
+
- The font family, such as "Open Sans", "Playfair Display"
+ The font family name (e.g., "Open Sans", "Playfair Display")
- The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
+ Font weight (e.g., 400, 700). Variable fonts support precise weights.
- The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2
-
-
- The font format, can be one of woff, woff2
-
-
-
-
-
- The font family, such as "Open Sans", "Playfair Display"
-
-
- The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
-
-
- The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2
-
-
- The font format, can be one of woff, woff2
-
-
+ Font file URL for custom fonts
-
-
-
-
- The font family, such as "Open Sans", "Playfair Display"
-
-
- The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
-
-
- The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2
-
-
- The font format, can be one of woff, woff2
-
-
+
+ Font format for custom sources
-
-
- Light / dark mode toggle settings
+## Navigation Structure
-
-
- The default light/dark mode. Defaults to system
-
-
- Whether to hide the light / dark mode toggle. Defaults to `true`.
-
-
-
+### Main Navigation
-
- Background color and decoration settings
-
-
-
+
+ Define your documentation's navigation structure.
-
-
-
-
-
-
+
+
+ Add external links that appear across all sections
-
- The background decoration of the theme
+
+ Organize content into logical groups
-
- The colors of the background
-
-
-
- The color in hex format to use in light mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
-
-
- The color in hex format to use in dark mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
-
-
+
+ Define individual documentation pages
-
-### Structure
+### Header & Footer
- Navbar content and settings
+ Configure the top navigation bar.
-
+
- The links in the navbar
-
-
-
-
-
- A valid path or external link
-
-
+ Navigation links in the header
-
-
-
-
-
-
-
- A valid path or external link
-
-
-
-
-
-
-
-
- The navigation structure of the content
-
-
-
- Add external links that will appear on all sections and pages irregardless of navigation nesting
-
-
-
-
-
-
- The name of the language in the ISO 639-1 format
-
-
- Whether this language is the default language
-
-
- Whether the current option is default hidden
-
-
- A valid path or external link
-
-
-
-
-
-
-
- The name of the version
-
- Minimum length: 1
-
-
- Whether this version is the default version
-
-
- Whether the current option is default hidden
-
-
- An external link
-
-
-
-
-
-
-
- The name of the tab
-
- Minimum length: 1
-
-
- The icon to be displayed in the section
-
-
- Whether the current option is default hidden
-
-
- An external link
-
-
-
-
-
-
-
- The name of the anchor
-
- Minimum length: 1
-
-
- The icon to be displayed in the section
-
-
-
-
-
- The color in hex format to use in light mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
-
-
- The color in hex format to use in dark mode
-
- Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$
-
-
-
-
- Whether the current option is default hidden
-
-
- A valid path or external link
-
-
-
-
-
-
- Organizing by languages
-
-
-
- Organizing by versions
-
-
-
- Organizing by tabs
-
-
-
- Organizing by anchors
-
-
-
- Organizing by groups
-
-
-
- An array of page paths or groups
-
+ Primary call-to-action button
-
- Footer configurations
+ Configure the footer content and layout.
-
+
- An object in which each key is the name of a social media platform, and each value is the url to your profile. For example:
- ```json
- {
- "x": "https://x.com/mintlify"
- }
- ```
-
- Valid property names: bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, twitter, website, x, youtube
+ Social media links
- The links to be displayed in the footer
-
-
-
- The header title of the column
-
- Minimum length: 1
-
-
- The links to be displayed in the column
-
-
-
- The label of the link
-
- Minimum length: 1
-
-
- The url of the link
-
-
-
-
+ Footer navigation links
-
-
- Banner configurations
-
-
-
- The content of the banner. This can be a string of text or a markdown string. For example:
- ```json
- {
- "content": "🚀 Banner is live! [Learn more](mintlify.com)"
- }
- ```
-
-
- Whether the banner is dismissible. Defaults to `false`.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-### API Configurations
+## API Documentation
- API reference configuration and playground settings
-
-
-
- A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s)
+ Settings for API reference documentation.
-
-
-
- Minimum length: 1
-
-
-
-
+
+
+ OpenAPI specification file(s)
- Configurations for the API playground
-
-
-
- The display mode of the API playground. Defaults to `interactive`.
-
-
- Whether to pass API requests through a proxy server. Defaults to `false`.
-
-
+ API playground configuration
- Configurations for the autogenerated API examples
-
-
-
- Example languages for the autogenerated API snippets
-
-
+ Code example settings
-
- Configurations for API pages generated from MDX files
-
-
-
- Authentication configuration for the API
-
-
-
- Authentication method for the API
-
-
- Authentication name for the API
-
-
-
-
-
-
-
-
-### SEO & Search
-
-
- SEO indexing configurations
-
-
-
- Meta tags added to every page. Must be a valid key-value pair
-
-
- Specify which pages to be indexed by search engines. Setting `navigable` indexes pages that are set in navigation, `all` indexes all pages. Defaults to `navigable`.
-
-
-
-
-
- Search display settings
-
-
-
- The prompt to be displayed in the search bar placeholder
-
-
-
-
-### Integrations
+## Analytics & Integrations
- Configurations for official integrations
+ Configure third-party integrations.
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Minimum length: 6
-
-
+ Amplitude analytics settings
-
-
-
-
- Must match pattern: ^G
-
-
-
-
-
-
-
-
- Must match pattern: ^G
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ Google Analytics 4 configuration
-
-
-
-
- Minimum length: 6
-
-
-
-
-
-
-
-
- Minimum length: 2
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Must match pattern: ^phc\_
-
-
-
-
-
-
-
-
-
-
-
-
-
+ Intercom chat widget settings
-
-
-
-
-
-
-
-
## Best Practices
-When configuring your `docs.json` file, consider these best practices:
-
-1. Keep the configuration organized by grouping related settings together
-2. Use meaningful names for groups and pages in your navigation structure
-3. Provide complete paths for all assets (logos, favicons, etc.)
-4. Test your configuration in both light and dark modes
-5. Verify all external links and integrations are correctly configured
-6. Use appropriate color contrasts for accessibility
-7. Configure SEO settings for better search engine visibility
-
-## Validation
-
-The `docs.json` file is validated against a JSON schema to ensure proper configuration. You can reference the schema by including:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json"
-}
-```
-
-## `mint.json` (Legacy)
-
-
- Every Mintlify site needs a `mint.json` file with the core configuration
- settings. Learn more about the [properties](#properties) or from an
- [example](#example-mint-json)
-
-## Properties
-
-### Styling
-
-{" "}
-
-
- Name of your company or project. Used for the global title.
-
-
-
- Path to logo image or object with path to "light" and "dark" mode logo images,
- and where the logo links to. SVG format is recommended. It does not pixelate
- and the file size is generally smaller.
-
-
-
- Path to the logo in light mode. For example: `/path/to/logo.svg`
-
-
-
- Path to the logo in dark mode. For example: `/path/to/logo.svg`
-
-
-
- Where clicking on the logo links you to
-
-
-
-
-
-
-{" "}
-
-
- Path to the favicon image. For example: `/path/to/favicon.svg`
-
-
-
- Hex color codes for your global theme
-
-
-
- The primary color. Used most often for highlighted content, section
- headers, accents, in light mode
-
-
-
- The primary color for dark mode. Used most often for highlighted content,
- section headers, accents, in dark mode
-
-
-
- The primary color for important buttons
-
-
-
- The color of the background in both light and dark mode
-
-
-
- The hex color code of the background in light mode
-
-
-
- The hex color code of the background in dark mode
-
-
-
-
-
-
-
-
-{" "}
-
-
- A preset theme configuration that changes the look and feel of the project. A
- theme is a set of default styling configurations. Examples:
- [Venus](https://starter-venus.mintlify.app),
- [Quill](https://starter-quill.mintlify.app),
- [Prism](https://starter-prism.mintlify.app)
-
-
-{" "}
-
-
- The global layout style of the documentation.
-
-
-
- Set a decorative background.
-
-
-
- The style of the decorative background.
-
-
-
-
+When configuring your `docs.json` file:
-{" "}
+1. Keep related settings grouped together
+2. Use meaningful names for navigation items
+3. Provide complete paths for all assets
+4. Test configurations in both light and dark modes
+5. Verify all external links
+6. Maintain appropriate color contrast
+7. Configure SEO settings properly
-
- Set a custom background image to be displayed behind every page.
-
-
-
+ Use JSON schema validation to ensure your configuration is correct. Add this to your `docs.json`:
+ ```json
+ {
+ "$schema": "https://mintlify.com/docs.json"
}
- >
- Custom fonts. Apply globally or set different fonts for headings and the body
- text.
+ ```
+
-Example:
+## Example Configuration
+
```json
-"font": {
- "headings": {
- "family": "Roboto"
+{
+ "name": "Mintlify",
+ "description": "Beautiful documentation that converts users",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
},
- "body": {
- "family": "Oswald"
- }
-}
-```
-
-
-
- The font family name. Custom fonts and all [Google
- Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans",
- "Playfair Display"
-
-
-
- The font weight. Precise values such as `560` are also supported for
- variable fonts. Check under the Styles section for your Google Font for
- the available weights.
-
-
-
- The URL to the font file. Can be used to specify a font that is not from
- Google Fonts.
-
-
-
- The font format. Required if using a custom font source (`url`).
-
-
-
-
-
-
-
- Customize the dark mode toggle.
-
-
-
- Set if you always want to show light or dark mode for new users. When not
- set, we default to the same mode as the user's operating system.
-
-
-
- Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
-
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
-
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
- }
- ```
-
-
-
-
-
-
-
-
- Customize the styling of components within the sidebar.
-
-
-
- The styling of the navigation item.
-
-
-
-
-
-
- Styling configurations for the topbar.
-
-
-
- The styling of the navigation item.
-
-
-
-
-
-
- The location options for the search bar.
-
-
-
- The location of the search bar.
-
-
-
-
-
-{" "}
-
-
- The style of the rounded edges.
-
-
-
- The style of the code block.
-
-
-
- `auto` will automatically switch between light and dark mode based on the
- user's system preferences.
-
-
-
-
-
-### Structure
-
-
- An array of groups with all the pages within that group
-
-
-
- The name of the group.
-
-
-
- The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
-
-
-
- The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders.
-
-
-
- The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin
-
-
-
-
-
-
-
- Array of names and urls of links you want to include in the topbar
-
-
-
- The name of the button.
-
-
-
- The url once you click on the button. Example: `https://mintlify.com/contact`
-
-
-
-
-
-
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided
- including the number of GitHub stars.
-
-
-
- If type is a link: What the button links to. If type is a github: Link to
- the repository to load GitHub information from.
-
-
-
- Text inside the button. Only required if type is a link.
-
-
-
- The style of the button.
-
-
-
- Whether to display the arrow
-
-
-
-
-
-
-
- Array of version names. Only use this if you want to show different versions
- of docs with a dropdown in the navigation bar.
-
-Versions can be leveraged for localization. You can store translated content
-under a version, and once you specify the `locale` any fixed text in Mintlify,
-such as 'Was this page helpful?', will automatically be translated based on the
-locale. We currently support localization in English, Chinese, Spanish, French,
-Japanese, and Portuguese.
-
-{" "}
-
-
- Localization auto-translates the UI and fixed assets in the docs, such as "Was
- this page helpful?". You must translate the content of the pages yourself.
-
-
-For more information, please refer to our
-[versioning & localization documentation](/navigation/versions).
-
-Example:
-
-
- ```json Default
- "versions": ["v1.0", "v1.1"]
- ```
-
- ```json Localization
- "versions": [
- {
- "name": "English",
- "locale": "en",
- },
- {
- "name": "Español",
- "locale": "es"
- }
- ]
- ```
-
-
-
-
-
- The version name.
-
-
-
- The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`.
-
-
-
- Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version.
-
-
-
-
-
-
-
- An array of the anchors, includes the icon, color, and url.
-
-{" "}
-
-{" "}
-
-
-
-{" "}
-
-{" "}
-
-
-
-
-
- The name of the anchor label.
-
- Example: `Community`
-
-
-
- The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
-
- Example: `comments`
-
-
-
- The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
-
-
-
- The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
-
-
-
- Used if you want to hide an anchor until the correct docs version is selected.
-
-
-
- Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
-
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
-
-
- Override the default configurations for the top-most anchor. Note: if you have
- tabs configured, this does not apply.
-
-
-
- The name of the top-most anchor
-
-
-
- Font Awesome icon.
-
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
-
-
- An array of navigational tabs.
-
-Example:
-
-```json
-"tabs": [
- {
- "name": "Writing Content",
- "url": "content"
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#16A34A",
+ "light": "#4ADE80",
+ "dark": "#166534"
},
- {
- "name": "API References",
- "url": "api-playground"
- }
-]
-```
-
-
-
- The name of the tab label.
-
-
-
- The start of the URL that marks what pages go in the tab. Generally, this
- is the name of the folder you put your pages in.
-
-
-
- Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
-
-
-
-
-
-
-
- An object to configure the footer with socials and links.
- Example:
-
-```json
-"footer": {
- "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
- "links": [
- {
- "title": "Column 1",
- "links": [
- { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
- ]
+ "navigation": {
+ "pages": ["introduction", "quickstart"],
+ "groups": [
+ {
+ "name": "Guides",
+ "pages": ["guides/getting-started", "guides/advanced"]
+ }
+ ]
+ },
+ "integrations": {
+ "ga4": {
+ "measurementId": "G-XXXXXXXXXX"
},
- {
- "title": "Column 2",
- "links": [
- { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
- { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
- ]
+ "intercom": {
+ "appId": "abc123"
}
- ]
-}
-```
-
-
-
- One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`
-
- Example: `x`
-
-
-
- The URL to the social platform.
-
- Example: `https://x.com/mintlify`
-
-
-
-
-
-
- Title of the column
-
-
-
- The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
-
-
-
-
-
-
-
- Configurations to enable feedback buttons
-
-
-
- Enables a rating system for users to indicate whether the page has been helpful
-
-
-
- Enables a button to allow users to suggest edits via pull requests for public repositories.
-
-
- If your docs repo is private, `suggestEdit` will not work.
-
-
-
-
- Enables a button to allow users to raise an issue about the documentation
-
-
-
-
-
-
-
- Configurations to change the search prompt
-
-
-
- Set the prompt for the search bar. Default is `Search...`
-
-
-
-
-
-### API Configurations
-
-
- Configuration for API settings. Learn more about API pages at [API Components](/api-playground).
-
-
-
- The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
- options that the user can toggle.
-
-
-
-
-
- The authentication strategy used for all API endpoints.
-
-
-
- The name of the authentication parameter used in the API playground.
-
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
-
-
- The default value that's designed to be a prefix for the authentication input field.
-
- E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
-
-
-
-
-
- Configurations for the API playground
-
-
-
- Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
-
- Learn more at the [playground guides](/api-playground)
-
-
-
- By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.
-
- Required for select request types, such as file uploads.
-
-
-
-
-
- Configurations for API requests
-
-
-
- Configurations for the auto-generated API request examples
-
-
-
- An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java`
-
-
-
-
-
-
-
- Configurations for the param fields in the API Playground
-
-
-
- The default expanded state of expandable options in the API playground.
-
- `"all"` - every expandable component is expanded
-
- `"topLevel"` - every top-level expandable component is expanded
-
- `"topLevelOneOfs"` - every top-level `oneOf` type is expanded
-
- `"none"` - every expandable component is closed (default behavior)
-
-
-
-
-
-
-
-
-
- A string or an array of strings of URL(s) or relative path(s) pointing to your
- OpenAPI file.
-
-Examples:
-
-
- ```json Absolute
- "openapi": "https://example.com/openapi.json"
- ```
-
- ```json Relative
- "openapi": "/openapi.json"
- ```
-
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
-
-
-
-
-
-### Integrations
-
-
- Configurations to add third-party integrations (excluding analytics integrations)
-
-
-
- Enables Intercom widget on docs site. The value should be your Intercom App ID.
-
-
-
- Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
-
-
-
-
-
-
-
- Configurations to add third-party analytics integrations. See full list of
- supported analytics [here](/integrations/analytics/overview).
-
-
-### Redirects
-
-
- An array of paths you want to configure to permanently redirect to another path
-
-Example:
-
-```json
-"redirects": [
- {
- "source": "/source/path",
- "destination": "/destination/path"
}
-]
-```
-
-
-
- The path that you want to redirect from.
-
- Example: `/source`
-
-
-
- The path that you want to redirect to.
-
- Example: `/destination`
-
-
-
-
-
-
-### Search Engine Optimization
-
-
- Settings for Search Engine Optimization.
-
-Example:
-
-```json
-"seo": {
- "indexHiddenPages": true
}
```
-
-
-
- Enables indexing pages not included in `navigation`.
-
-
-
-
-
-## Example `mint.json`
-
-Click on the following dropdown to view a sample configuration file
-
-
- ```json
- {
- "name": "Mintlify",
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg"
- },
- "favicon": "/favicon.svg",
- "colors": {
- "primary": "#16A34A",
- "light": "#4ADE80",
- "dark": "#166534"
- },
- "topbarLinks": [
- {
- "name": "Contact Us",
- "url": "mailto:support@mintlify.com"
- }
- ],
- "topbarCtaButton": {
- "name": "Get Started",
- "url": "https://mintlify.com/start"
- },
- "anchors": [
- {
- "name": "API Components",
- "icon": "rectangle-terminal",
- "color": "#f59f0b",
- "url": "api-components"
- },
- {
- "name": "Community",
- "icon": "comments",
- "color": "#2564eb",
- "url": "https://mintlify.com/community"
- }
- ],
- "navigation": [
- {
- "group": "Getting Started",
- "pages": ["introduction", "quickstart"]
- },
- {
- "group": "API Components",
- "pages": ["api-playground/overview", "api-playground/configuration"]
- },
- {
- "group": "Settings",
- "pages": ["settings/global", "settings/page"]
- },
- {
- "group": "Analytics",
- "pages": ["analytics/posthog"]
- }
- ],
- "footerSocials": {
- "github": "https://github.com/mintlify",
- "slack": "https://mintlify.com/community",
- "x": "https://x.com/mintlify"
- },
- "integrations": {
- "intercom": "APP_ID",
- "frontchat": "CHAT_ID"
- }
- }
- ```
-
+
+
+ Remember to validate your configuration after making changes. Use the Mintlify CLI to test your documentation locally before deploying.
+
\ No newline at end of file
diff --git a/text.mdx b/text.mdx
index 45cec919..a0238b08 100644
--- a/text.mdx
+++ b/text.mdx
@@ -4,86 +4,121 @@ description: "Text, title, and styling in standard markdown"
icon: 'heading'
---
-## Titles
+## Document Structure
-Best used for section headers.
+### Page Titles and Headings
+
+Headers help organize your content into a clear hierarchy. Use them to create logical sections that are easy to navigate.
+
+#### Main Section Headers (H2)
+
+Best used for major section headers. Create these with double hashtags:
```md
-## Titles
+## Main Section
```
-### Subtitles
+#### Subsection Headers (H3)
-Best used for subsection headers.
+Best used for breaking down main sections into smaller topics. Create these with triple hashtags:
```md
-### Subtitles
+### Subsection
```
-
-Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
-
+Each heading automatically creates:
+- An anchor link for direct navigation
+- An entry in the table of contents
-## Text Formatting
+## Text Styling and Formatting
+
+### Basic Text Formatting
-We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
+Markdown provides several ways to format your text for emphasis. Here are the most common styles:
-| Style | How to write it | Result |
+| Style | Syntax | Example Output |
| ------------- | ----------------- | --------------- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | _italic_ |
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
-You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
+### Combined Formatting
-You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
+You can combine multiple styles together. For example:
+- `**_bold and italic_**` renders as **_bold and italic_**
-| Text Size | How to write it | Result |
-| ----------- | ------------------------ | ---------------------- |
-| Superscript | `superscript` | superscript |
-| Subscript | `subscript` | subscript |
+### Special Text Formatting
-## Linking to Pages
+For technical and mathematical writing, you may need superscript and subscript text:
-You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
+| Format | HTML Syntax | Result |
+| ---------- | ----------------------- | ---------------------- |
+| Superscript| `superscript`| superscript |
+| Subscript | `subscript` | subscript |
-Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page "Text" in our components section.
+## Hyperlinks and Navigation
-Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
+### Internal Documentation Links
-You can validate broken links in your docs with [our CLI](/development).
+When linking to other pages in your documentation:
-## Blockquotes
+- Use root-relative paths starting with `/`
+- Example: `[Text Guide](/content/text)`
-### Singleline
+
+Avoid using relative paths like `../text` as they impact load performance.
+
-To create a blockquote, add a `>` in front of a paragraph.
+### External Links
-> Dorothy followed her through many of the beautiful rooms in her castle.
+For linking to external websites:
```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
+[Link Text](https://example.com)
```
-### Multiline
+
+Use our CLI to validate all documentation links. Learn more in our [Development Guide](/development).
+
+
+## Block Content
+
+### Blockquotes
+
+Blockquotes help emphasize quoted text or important notes. Create them by adding `>` before text.
-> Dorothy followed her through many of the beautiful rooms in her castle.
+#### Single-line Blockquotes
+
+> This is a single-line blockquote example.
+
+```md
+> This is a single-line blockquote example.
+```
+
+#### Multi-line Blockquotes
+
+> This is the first line of a multi-line blockquote.
>
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+> This is the second line, separated by a blank line with `>`.
```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
+> This is the first line of a multi-line blockquote.
>
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+> This is the second line, separated by a blank line with `>`.
```
-### LaTeX
+## Mathematical Notation
+
+### Inline LaTeX
+
+For mathematical expressions within text, use single dollar signs:
+- Example: `$a^2 + b^2 = c^2$` renders as $(a^2 + b^2 = c^2)$
-Mintlify supports in-line [LaTeX](https://www.latex-project.org) by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$.
+### Block LaTeX
-Equations on their own line can be created with double dollar signs (\$\$):
+For standalone mathematical expressions, use double dollar signs:
$$\exists \, x \notin [0,1]$$
@@ -91,16 +126,21 @@ $$\exists \, x \notin [0,1]$$
$$\exists \, x \notin [0,1]$$
```
-### Line Breaks
+## Text Layout
-Markdown syntax also recognizes a double enter in your MDX as a linebreak.
+### Paragraph Spacing
-```html
-
-```
+Create clear separation between paragraphs using:
+- Double line breaks in your markdown
+- HTML `
` tags for explicit line breaks
+Example:
```md
-Paragraph 1
+First paragraph
-Paragraph 2
+Second paragraph
```
+
+
+Consistent spacing improves readability and makes your content more accessible to both humans and AI systems.
+
\ No newline at end of file