diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 17203bcde..9d17e6f15 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,14 +1,68 @@ --- -title: 'Playground' -description: 'Enable users to interact with your API' +title: 'API Playground' +description: 'Try out API endpoints directly in your documentation' openapi: 'GET /plants/{id}' hideApiMarker: true icon: 'play' --- -The API playground is an interactive environment to make requests and preview an API endpoint. +The API Playground lets you test API endpoints right from your documentation. Think of it as a built-in API testing tool - no need to switch to Postman or other external tools! - - Autogenerating API pages with OpenAPI will automatically generate API - playground. Read more about using OpenAPI [here](/api-playground/openapi). - +## What Can You Do in the Playground? + + + + Make real API calls and see responses instantly + + + Input your own values for path, query, and body parameters + + + Add your API keys and authentication tokens + + + See formatted API responses with syntax highlighting + + + +## Getting Started + +The playground appears automatically on API documentation pages. Here's what you'll typically see: + +1. **Authentication Fields** - Where you enter API keys or tokens +2. **Parameter Inputs** - Fields to enter your request data +3. **Try It Button** - Click to make the API call +4. **Response Section** - Shows the API response after your call + + + If you're using OpenAPI to document your API, the playground will be generated automatically! + Learn more about OpenAPI setup [here](/api-playground/openapi). + + +## Example Playground + +Here's a simple example of what the playground looks like in action: + + + ![API Playground Example](/images/api-playground-example.png) + + +## Tips for Using the Playground + + + + The playground will pre-fill example values from your OpenAPI spec, making it faster to test endpoints. + + + + Try various parameter combinations to see how the API responds in different situations. + + + + Intentionally send invalid data to see how error responses look and understand error handling. + + + + + Keep your API keys handy! You'll need them to make authenticated requests in the playground. + \ No newline at end of file diff --git a/development.mdx b/development.mdx index 0759b0faa..5694e5497 100644 --- a/development.mdx +++ b/development.mdx @@ -1,134 +1,158 @@ --- title: "Local Development" -description: "Preview changes locally to update your docs" +description: "Step-by-step guide to preview and test your documentation locally" --- - - **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - + + Before you begin, make sure you have Node.js version 19 or higher installed on your computer. You can check your Node.js version by running `node --version` in your terminal. + -**Step 1**: Install the Mintlify CLI: +## Setting Up Your Environment - +### Installing the CLI Tool + +First, you'll need to install the Mintlify command-line interface (CLI). Choose one of these commands based on your package manager: + ```bash npm npm i -g mintlify ``` - ```bash yarn yarn global add mintlify ``` - ```bash pnpm pnpm add -g mintlify ``` - -**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command: +### Running the Development Server -```bash -mintlify dev -``` +Once installed, follow these steps: -Alternatively, if you do not want to install the CLI globally you can use a run script available: + + + Open your terminal and go to your documentation directory (where your `docs.json` file is located). + + + + Run this command to start your local development server: + ```bash + mintlify dev + ``` + - + + Open your browser and visit `http://localhost:3000` to see your documentation. + + -```bash npm -npx mintlify dev -``` + + Don't want to install the CLI globally? You can use these run commands instead: + + ```bash npm + npx mintlify dev + ``` -```bash yarn -yarn dlx mintlify dev -``` - - -```bash pnpm -pnpm dlx mintlify dev -``` + ```bash yarn + yarn dlx mintlify dev + ``` - - - - Yarn's "dlx" run script requires yarn version \>2. See [here](https://yarnpkg.com/cli/dlx) for more information. - + ```bash pnpm + pnpm dlx mintlify dev + ``` + + -A local preview of your documentation will be available at `http://localhost:3000`. +## Common Tasks -### Custom Ports +### Using a Different Port -By default, Mintlify uses port 3000. You can customize the port using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +Need to run on a different port? Use the `--port` flag: ```bash mintlify dev --port 3333 ``` -If you attempt to run on a port that's already in use, it will use the next available port: + + If the port you specify is already in use, Mintlify will automatically try the next available port. + + +### Checking for Broken Links + +Keep your documentation reliable by checking for broken links: -```md -Port 3000 is already in use. Trying 3001 instead. +```bash +mintlify broken-links ``` -## Versions +### Updating Your CLI Version -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: +To ensure you're using the latest features, regularly update your CLI: - ```bash npm npm i -g mintlify@latest ``` - ```bash yarn yarn global upgrade mintlify ``` - ```bash pnpm pnpm up --global mintlify ``` - -## Validating Links +## Best Practices -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +### Code Formatting +For the best writing experience, we recommend: -```bash -mintlify broken-links -``` + + + Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting + + + Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to automatically format your documentation + + + +## Troubleshooting Guide + + + + Try these steps in order: + 1. Check your Node.js version (`node --version`) + 2. Delete the `~/.mintlify` folder + 3. Reinstall the CLI: `npm remove -g mintlify && npm install -g mintlify` + + + + This usually means you need to update Node.js: + 1. Remove Mintlify: `npm remove -g mintlify` + 2. Update to Node.js v19 or higher + 3. Reinstall: `npm install -g mintlify` + + + + Try these solutions: + 1. Clear your browser cache + 2. Restart the development server + 3. Check for syntax errors in your MDX files + + -## Deployment +## Deployment Status -If the deployment is successful, you should see the following: +When your deployment succeeds, you'll see green checkmarks in your GitHub status: Successful deployment status showing green checkmarks - - -## Code Formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting - - - - This may be due to an outdated version of node. Try the following: - - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` - - - Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run `mintlify dev` again. - - \ No newline at end of file + \ No newline at end of file diff --git a/docs.json b/docs.json index edd11836e..29838ad0a 100644 --- a/docs.json +++ b/docs.json @@ -22,7 +22,12 @@ { "group": "Editing", "icon": "pen-paintbrush", - "pages": ["development", "web-editor"] + "pages": [ + "development", + "web-editor", + "quickstart", + "development" + ] }, "settings/global", { @@ -37,7 +42,9 @@ ] }, "themes", - "migration" + "migration", + "text", + "settings/global" ] }, { @@ -72,7 +79,8 @@ "api-playground/mdx/authentication" ] }, - "api-playground/troubleshooting" + "api-playground/troubleshooting", + "api-playground/overview" ] }, { @@ -262,7 +270,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -374,4 +384,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index bc95e6932..7242da57c 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,6 +1,6 @@ --- title: "Quickstart" -description: "Start building modern documentation in under five minutes" +description: "Get your documentation site up and running in minutes" icon: "rocket" --- @@ -15,172 +15,110 @@ icon: "rocket" /> -## Getting Started - -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. - -### Creating the Repository - -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. - - - - - - 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. - - - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - - - - - - 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) - - Monorepo setup - Monorepo setup - - - - - -### Updating the Content - -Mintlify enables you to easily customize the style, structure, and content of -your docs. - - - - - 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). - - - - - - Learn more about how to use the web editor on our [guide](/web-editor). - - - - - - Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations: - - ```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", - }, - ``` - - A full list of supported configurations can be found at [global settings](/settings/global). - - - - - - Add content with simple MDX files. Initiate your pages with this template: - - ```md - --- - title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" - --- - ``` - - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). - - - - - - 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). - - - ![Manual - Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) - - - - - - - You can easily set up your API references using an OpenAPI document. - - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL. - - ```json - "openapi": "link-to-your-openapi-file" - ``` - - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: - - ```bash - npx @mintlify/scraping@latest openapi-file - ``` - - 3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`. - - 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). - - - - - - 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). +## Quick Setup Guide + +Let's get your documentation site up and running with these simple steps. + +### 1. Create Your Documentation Site + + + + Choose one of these easy ways to start: + - Visit our [dashboard](https://dashboard.mintlify.com) and follow the guided setup + - Clone our [starter template](https://github.com/mintlify/starter) directly from GitHub + + + + Install our GitHub app to enable automatic deployments: + 1. Go to [dashboard settings](https://dashboard.mintlify.com/settings) + 2. Click the GitHub installation link + 3. Follow the prompts to connect your repository + + + +### 2. Edit Your Content + +Choose the editing method that works best for you: + + + + Perfect for developers who prefer their own tools: + 1. Clone your repository + 2. Install Mintlify CLI: `npm i -g mintlify` + 3. Run `mintlify dev` to preview changes + + + + Easy for non-technical team members: + 1. Visit our [web editor](/web-editor) + 2. Make changes directly in your browser + 3. Preview in real-time + + + +### 3. Basic Customization + +Make your docs feel like home with these simple customizations in your `docs.json`: + +```json +{ + "name": "Your Company", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "colors": { + "primary": "#2AB673" + } +} +``` + + + Need help choosing colors? Use your brand's primary color as a starting point. + + +### 4. Add Your Content + +Create new pages easily with this simple format: + +```md +--- +title: "Your Page Title" +description: "A brief description of your page" +--- - - +Start writing your content here! +``` - 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). + Use our [component library](/content/components) to add interactive elements like tabs, accordions, and callouts to make your docs more engaging. -### Publishing +### 5. Publish Your Docs - +Ready to share your docs with the world? Just push your changes to GitHub, and we'll handle the rest automatically. -Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan. +Want your docs on your own domain? Add it through your [dashboard settings](https://dashboard.mintlify.com/settings). -Navigate to your [dashboard settings](https://dashboard.mintlify.com/settings) to add a custom domain. +## Next Steps -![Custom Domain](/images/custom-domain.png) +Here are some helpful resources to explore: - + + + Learn how to document your APIs with OpenAPI + + + Explore all customization options + + + Browse our library of ready-to-use components + + + Join our community for help and tips + + -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 migrating existing docs? Our Enterprise plan includes white-glove migration service. [Contact us](mailto:sales@mintlify.com) to learn more. + \ No newline at end of file diff --git a/settings/global.mdx b/settings/global.mdx index eff6eb9cd..652b74b8b 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -1,1548 +1,234 @@ --- title: "Global Settings" -description: "Configure your documentation using the `docs.json` file" +description: "Configure your documentation settings in the docs.json file" 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. +Every documentation site needs a `docs.json` file to control its core settings. This file is where you'll configure everything about your docs - from how they look to how they work. -## Properties +## Essential Settings -### Customization +Let's start with the most important settings you'll need to configure: - - The layout theme of the project. Examples: - [Maple](https://maple.mintlify.app/), [Palm](https://palm.mintlify.app/), - +### Basic Information - The name of the project, organization, or product Minimum length: 1 + The name of your project or company that will appear throughout the docs. + + Example: `"name": "My Amazing Project"` - Optional description used for SEO and LLM indexing + A brief description of your project. This helps with SEO and gives context to AI models. + + Example: `"description": "The easiest way to build amazing things"` -### Styling +### Theme & Colors - - The colors to use in your documentation. At the very least, you must define the primary color. For example: - ```json - { - "colors": { - "primary": "#ff0000" - } - } - ``` + + Choose a pre-built theme for your docs. Each theme has its own unique style: + - Mint: Clean and modern + - Maple: Warm and traditional + - Palm: Bold and vibrant + + Example: `"theme": "mint"` + + - The primary color of the theme + The main color used throughout your docs. Should be a hex color code. - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Example: `"primary": "#0066FF"` - The light color of the theme. Used for dark mode + A lighter version of your primary color for dark mode. Should be a hex color code. - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ + Example: `"light": "#66A3FF"` - The dark color of the theme. Used for light mode + A darker version of your primary color for light mode. Should be a hex color code. - Must match pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$ - - - - - - The logo (for both light and dark mode) - - - - Path pointing to the light logo file to use in dark mode, including the file extension. Example: `/logo.png` - - - Path pointing to the dark logo file to use in light mode, including the file extension. Example: `/logo-dark.png` - - - The URL to redirect to when clicking the logo. If not provided, the logo will link to the homepage. Example: `https://example.com` - - - - - - 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` - - - - Path pointing to the light favicon file to use in dark mode, including the file extension. Example: `/favicon.png` - - - Path pointing to the dark favicon file to use in light mode, including the file extension. Example: `/favicon-dark.png` - - - - - - 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`. + Example: `"dark": "#004DC2"` - - - - - - - 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 - - - - - - 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 - - - - - - - - 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 - - - - +Example color configuration: +```json +{ + "colors": { + "primary": "#0066FF", + "light": "#66A3FF", + "dark": "#004DC2" + } +} +``` - - Light / dark mode toggle settings +### Branding - - - The default light/dark mode. Defaults to system - - - Whether to hide the light / dark mode toggle. Defaults to `true`. - - + + Your logo image(s). You can use: + - A single logo: `"logo": "/logo.svg"` + - Different logos for light/dark modes: + ```json + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg", + "href": "https://mysite.com" // Optional: where the logo links to + } + ``` - - Background color and decoration settings - - - - - - - - - - - - - The background decoration of the theme - - - 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})$ - - - - - + + The icon shown in browser tabs. Can be: + - A single favicon: `"favicon": "/favicon.ico"` + - Different favicons for light/dark modes: + ```json + "favicon": { + "light": "/favicon-light.ico", + "dark": "/favicon-dark.ico" + } + ``` -### Structure - - - Navbar content and settings - - - - The links in the navbar - - - - - - A valid path or external link - - - - - - - - - - - - A valid path or external link - - - - - - +## Navigation & Structure - 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 - - - - + Define how users move through your documentation. Here's a basic example: - - - 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 - - - - - - - - Footer configurations - - - - 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 +```json +{ + "navigation": { + "groups": [ { - "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 - - - 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 - - - - - - - - - - - Banner configurations - - - - The content of the banner. This can be a string of text or a markdown string. For example: - ```json + "name": "Getting Started", + "pages": ["introduction", "quickstart"] + }, { - "content": "🚀 Banner is live! [Learn more](mintlify.com)" + "name": "Guides", + "pages": ["guides/installation", "guides/configuration"] } - ``` - - - Whether the banner is dismissible. Defaults to `false`. - - - - - - - - - - - - - - - - -### API Configurations - - - API reference configuration and playground settings - - - - A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s) - - - - - Minimum length: 1 - - - - - - - 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`. - - - - - Configurations for the autogenerated API examples - - - - Example languages for the autogenerated API snippets - - - - - 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. Possible options [here](https://mintlify.com/docs/settings/seo#supported-meta-tags) - - - 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 - - - Configurations for official integrations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Minimum length: 6 - - - - - - - - - Must match pattern: ^G - - - - - - - - - Must match pattern: ^G - - - - - - - - - - - - - - - - - - - - - - - - - Minimum length: 6 - - - - - - - - - Minimum length: 2 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Must match pattern: ^phc\_ - - - - - - - - - - - - - - - - - - - - - - - - - -## 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. - - - - - -{" "} - - - Set a custom background image to be displayed behind every page. - - - - Custom fonts. Apply globally or set different fonts for headings and the body - text. - -Example: + + Customize your top navigation bar: ```json -"font": { - "headings": { - "family": "Roboto" - }, - "body": { - "family": "Oswald" +{ + "navbar": { + "links": [ + { + "label": "Blog", + "href": "https://blog.mysite.com" + } + ], + "primary": { + "type": "button", + "label": "Get Started", + "href": "/quickstart" + } } } ``` - - - - 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 [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon for the group. Note: this only applies to sub-folders. - - - - The type of icon (only for [Font Awesome](https://fontawesome.com/icons) icons). 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/icons) or [Lucide](https://lucide.dev/icons) 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. +## Appearance Settings -Example: - -```json -"tabs": [ - { - "name": "Writing Content", - "url": "content" - }, + + Control light/dark mode settings: + ```json { - "name": "API References", - "url": "api-playground" + "appearance": { + "default": "system", // Can be "light", "dark", or "system" + "strict": true // Hide the theme toggle button + } } -] -``` - - - - 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" } - ] - }, - { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] + + Customize your docs' background: + ```json + { + "background": { + "color": { + "light": "#ffffff", + "dark": "#090014" + }, + "decoration": "gradient" // Can be "gradient", "grid", or "windows" } - ] -} -``` - - - - 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 +## SEO & Analytics -Example: - -```json -"redirects": [ + + Improve your docs' search engine visibility: + ```json { - "source": "/source/path", - "destination": "/destination/path" + "seo": { + "metatags": { + "og:title": "My Amazing Docs", + "og:description": "Learn how to build amazing things" + }, + "indexing": "all" // Index all pages, or "navigable" for only nav pages + } } -] -``` - - - - The path that you want to redirect from. - - Example: `/source` - - - - The path that you want to redirect to. - - Example: `/destination` - - - - - + ``` + -### Search Engine Optimization + + Configure the search experience: + ```json + { + "search": { + "prompt": "Search the docs..." + } + } + ``` + - - Settings for Search Engine Optimization. +## Quick Start Example -Example: +Here's a minimal `docs.json` to get you started: ```json -"seo": { - "indexHiddenPages": true +{ + "name": "My Project", + "theme": "mint", + "colors": { + "primary": "#0066FF" + }, + "logo": "/logo.svg", + "favicon": "/favicon.ico", + "navigation": { + "groups": [ + { + "name": "Getting Started", + "pages": ["introduction", "quickstart"] + } + ] + } } ``` - - - Enables indexing pages not included in `navigation`. - - - - - -## Example `mint.json` +## Best Practices -Click on the following dropdown to view a sample configuration file +1. **Start Simple**: Begin with essential settings and add more as needed +2. **Test Colors**: Ensure your chosen colors have good contrast in both light and dark modes +3. **Organize Navigation**: Group related pages together logically +4. **Use Clear Names**: Make navigation labels and page titles descriptive and user-friendly +5. **Check Mobile**: Preview your docs on mobile devices to ensure good responsive design - - ```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" - } - } - ``` - - +Need help? Check our [community forum](https://mintlify.com/community) for support and examples from other users. \ No newline at end of file diff --git a/text.mdx b/text.mdx index 45cec9193..c716df4f1 100644 --- a/text.mdx +++ b/text.mdx @@ -1,106 +1,146 @@ --- title: "Headers and Text" -description: "Text, title, and styling in standard markdown" +description: "A beginner's guide to text formatting in markdown" icon: 'heading' --- -## Titles +## Headers -Best used for section headers. +Headers help organize your content into sections. Use `#` symbols - more `#` means a smaller header. ```md -## Titles -``` - -### Subtitles - -Best used for subsection headers. - -```md -### Subtitles +## Large Header +### Medium Header +#### Small Header ``` - -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. - +Headers automatically create: +- Anchor links to jump to sections +- Table of contents entries on the right -## Text Formatting +## Basic Text Formatting -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. +Here are the most common ways to format your text: -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | + + ```md Write it like this + **bold text** + _italic text_ + ~strikethrough~ + ``` -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. + ```md It shows up like this + **bold text** + _italic text_ + ~strikethrough~ + ``` + -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. +### Combining Formats -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | +You can mix and match formatting styles: -## Linking to Pages + + ```md Example + **_bold and italic_** + ~**bold and strikethrough**~ + ``` -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). + ```md Result + **_bold and italic_** + ~**bold and strikethrough**~ + ``` + -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. +## Special Text Formats -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. +### Superscript and Subscript -You can validate broken links in your docs with [our CLI](/development). +Use HTML tags for raised or lowered text: -## Blockquotes + + ```md Example + Normal text with raised text + Normal text with lowered text + ``` -### Singleline + ```md Result + Normal text with raised text + Normal text with lowered text + ``` + -To create a blockquote, add a `>` in front of a paragraph. +## Adding Links -> Dorothy followed her through many of the beautiful rooms in her castle. +Links are easy! Put the text in `[]` and the URL in `()`: ```md -> Dorothy followed her through many of the beautiful rooms in her castle. +[Click here](https://example.com) ``` -### Multiline +### Internal Doc Links -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. +When linking to other pages in your docs: +- ✅ Use root-relative paths: `/content/text` +- ❌ Avoid relative paths: `../text` ```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. +[See our guide](/content/text) ``` -### LaTeX +## Blockquotes + +Add quotes or callouts using `>`: + + + ```md Single Line Quote + > This is a simple quote + ``` + + ```md Multi-line Quote + > First line of the quote + > + > Second line of the quote + ``` + + +Results in: +> First line of the quote +> +> Second line of the quote -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)$. +## Mathematical Expressions (LaTeX) -Equations on their own line can be created with double dollar signs (\$\$): +### Inline Math +Use single `$` for math within text: `$E = mc^2$` becomes $E = mc^2$ -$$\exists \, x \notin [0,1]$$ +### Display Math +Use double `$$` for standalone equations: ```md -$$\exists \, x \notin [0,1]$$ +$$\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}$$ ``` -### Line Breaks +Becomes: +$$\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}$$ -Markdown syntax also recognizes a double enter in your MDX as a linebreak. +## Line Breaks -```html -
-``` +Create space between paragraphs by: +- Pressing Enter twice +- Using the `
` HTML tag -```md -Paragraph 1 + + ```md Double Enter + First paragraph -Paragraph 2 -``` + Second paragraph + ``` + + ```md HTML Break + First line
+ Second line + ``` + \ No newline at end of file