From e866b427349716cd5906bd9095cd11f7a82a11dd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 8 Jan 2025 23:13:39 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- api-playground/mdx/configuration.mdx | 37 +- integrations/analytics/overview.mdx | 599 +------------------- integrations/sdks/speakeasy.mdx | 55 +- integrations/sdks/stainless.mdx | 26 +- migration.mdx | 135 +---- quickstart.mdx | 214 ++----- settings/global.mdx | 809 +-------------------------- 7 files changed, 153 insertions(+), 1722 deletions(-) diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 55682df30..059eebb7a 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -3,25 +3,24 @@ title: 'MDX Setup' description: 'Generate docs pages for your API endpoints using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Learn how to set up API documentation using MDX, which will automatically generate an API playground, request examples, and response examples. - - In your `mint.json` file, define your base URL and auth method: + + Add your API configuration to `mint.json`: ```json { "api": { - "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs + "baseUrl": "https://mintlify.com/api", "auth": { - "method": "bearer" // options: bearer, basic, key. + "method": "bearer" } } } ``` - If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field: - + To hide the API playground, use: ```json { "api": { @@ -32,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js } ``` - Find a full list of API configurations [here](/settings/global#api-configurations). + See all API configurations [here](/settings/global#api-configurations). - - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + + Create MDX files for each endpoint with the following format: ```md --- @@ -46,20 +44,13 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js --- ``` - You can specify path parameters by adding the parameter name to the path, wrapped with `{}`: - + For paths with parameters, use `{paramName}`: ```bash - https://api.example.com/v1/endpoint/{userId} + /v1/endpoint/{userId} ``` - - - - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. - - - - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation). + + Add your endpoint pages to the `navigation` field in `mint.json`. Learn more [here](/settings/navigation). - + \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index fe9574b9b..cdc809523 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -1,593 +1,46 @@ --- title: "Analytics Integrations" -description: "Integrate with an analytics platform to track events" +description: "Track documentation engagement with your preferred analytics platform" --- -Automatically send data about your documentation engagement to your third party analytics provider. - -## All Integrations +## Available Integrations - - - - }> - - - - - - - - } -> - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> - + }> + }> + }> + }> + }> -## Enabling Analytics - -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. +## Setup -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +Add your analytics configuration to `mint.json`: - - -```json Analytics options in mint.json -"analytics": { - "amplitude": { - "apiKey": "required" - }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, +```json +{ + "analytics": { "ga4": { - "measurementId": "required" - }, - "gtm": { - "tagId": "required" + "measurementId": "G-XXXXXXX" }, "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" - }, - "mixpanel": { - "projectToken": "required" - }, - "pirsch": { - "id": "required" - }, - "plausible": { - "domain": "required" - }, - "posthog": { - "apiKey": "required", - "apiHost": "optional" - }, -} -``` - -```json Google Analytics 4 Example -"analytics": { - "ga4": { - "measurementId": "G-XXXXXXX" + "hjid": "XXXXX", + "hjsv": "X" } + // Add other platforms as needed + } } ``` - - -## FAQ +## Available Events - +Key user interactions are automatically tracked, including: -- `expandable_open` -- `expandable_close` -- `accordion_open` -- `accordion_close` -- `header_nav_item_click` -- `cta_click` -- `scroll_to_bottom` -- `search_close` -- `api_playground_call` -- `search_result_click` -- `chat_enter` -- `chat_followup` -- `chat_completed` -- `code_block_copy` -- `chat_shared` -- `thumb_vote` -- `powered_by_mintlify_click` -- `ai_chat_citation_click` -- `ai_chat_feedback_positive_click` -- `ai_chat_feedback_negative_click` +- Search usage +- Navigation clicks +- API playground interactions +- Chat interactions +- Code block copies +- Scroll behavior - +Each analytics platform receives these events in their standard format. Visit the individual integration pages for platform-specific details. \ No newline at end of file diff --git a/integrations/sdks/speakeasy.mdx b/integrations/sdks/speakeasy.mdx index d45628bed..93d286e46 100644 --- a/integrations/sdks/speakeasy.mdx +++ b/integrations/sdks/speakeasy.mdx @@ -3,11 +3,13 @@ title: Speakeasy description: Automate your SDK usage snippets in the API playground --- -You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of your Mintlify-powered documentation. +Speakeasy allows you to automatically generate and integrate SDK code snippets into your Mintlify API reference documentation. These snippets will appear in your [interactive playground](https://mintlify.com/docs/api-playground/overview). -## Speakeasy SDK Repository Changes +## Setup Instructions -In your Speakeasy SDK repos, add the following to the `targets` section of your `.speakeasy/workflow.yaml` file to ensure code samples are automatically produced alongside SDK generations. +### 1. Configure Your SDK Repository + +Add the following to the `targets` section in your SDK's `.speakeasy/workflow.yaml`: ```yaml .speakeasy/workflow.yaml targets: @@ -18,55 +20,40 @@ targets: output: codeSamples.yaml ``` -Code samples will be generated in the form of an [OpenAPI overlay file](https://www.speakeasyapi.dev/openapi/overlays) that will be used in the Mintlify docs repository. - -## Mintlify Docs Repository Changes - -The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, `openapi.yaml`. Mintlify will use this output file when constructing your API reference. +### 2. Set Up Your Documentation Repository -### Interactive CLI Set Up +You can set up your documentation repository using either the CLI or manual configuration. -Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI. +#### Option A: Using the CLI (Recommended) +Run these commands: ```bash speakeasy configure sources speakeasy configure github ``` -Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it's often the same specification used to power Mintlify docs. - -![](/images/speakeasy-1.webp) - -Add the overlay created by Speakeasy to inject code snippets into your spec. - -![](/images/speakeasy-2.webp) +Follow the CLI prompts to: +1. Set up your source OpenAPI spec +2. Add the Speakeasy overlay for code snippets +3. Configure the output path for the final spec -Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify. - -![](/images/speakeasy-3.webp) - -Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab. - -## Manual Set Up - -Alternatively, you can manually set up the following files in your Mintlify docs repo. +#### Option B: Manual Configuration +Create the following files in your documentation repository: ```yaml .speakeasy/workflow.yaml workflowVersion: 1.0.0 sources: docs-source: inputs: - - location: {{your_api_spec}} # local or remote references supported + - location: {{your_api_spec}} overlays: - - location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/codeSamples.yaml - - location: https://raw.githubusercontent.com/{{your_sdk_repo_2}}/codeSamples.yaml - - location: https://raw.githubusercontent.com/{{your_sdk_repo_3}}/codeSamples.yaml + - location: https://raw.githubusercontent.com/{{your_sdk_repo}}/codeSamples.yaml output: openapi.yaml targets: {} ``` -```yaml .speakeasy/workflows/sdk_generation.yaml +```yaml .github/workflows/sdk_generation.yaml name: Generate permissions: checks: write @@ -94,4 +81,8 @@ jobs: speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }} ``` -Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab. +### 3. Add Your API Key + +Add your `SPEAKEASY_API_KEY` to your repository secrets: +1. Go to `Settings > Secrets & Variables > Actions` +2. Add your Speakeasy API key (found in the Speakeasy dashboard under **API Keys**) \ No newline at end of file diff --git a/integrations/sdks/stainless.mdx b/integrations/sdks/stainless.mdx index 8a21bfab4..c8ab1c3ff 100644 --- a/integrations/sdks/stainless.mdx +++ b/integrations/sdks/stainless.mdx @@ -3,18 +3,21 @@ title: Stainless description: Automate your SDK example snippets in the API playground --- -If you use Mintlify's OpenAPI support for your API reference documentation, add the following to your Stainless config: +To integrate Stainless with your Mintlify documentation: + +1. Add this to your Stainless config: ```yaml openapi.stainless.yml openapi: code_samples: mintlify ``` -Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so: +2. Set up the [OpenAPI configuration](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. +3. Create a GitHub Action to sync your OpenAPI spec: ```yaml -name: Upload OpenAPI spec to Stainless and (Mintlify) docs repo +name: Sync OpenAPI Spec on: push: @@ -26,27 +29,26 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Push spec and config to Stainless and outputs documented spec + - name: Push to Stainless uses: stainless-api/upload-openapi-spec-action@main with: input_path: 'path/to/my-company-openapi.json' config_path: 'path/to/my-company.stainless.yaml' output_path: 'path/to/my-company-openapi.documented.json' project_name: 'my-stainless-project' - - name: Push documented spec to docs repo + - name: Sync with docs repo uses: dmnemec/copy_file_to_another_repo_action@main env: API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }} with: source_file: 'config/my-company-openapi.documented.json' destination_repo: '{DOCS_REPO_NAME}' - destination_folder: 'openapi-specs' # (optional) the folder in the destination repository to place the file in, if not the root directory - user_email: '{EMAIL}' # the email associated with the GH token - user_name: '{USERNAME}' # the username associated with the GH token + destination_folder: 'openapi-specs' + user_email: '{EMAIL}' + user_name: '{USERNAME}' commit_message: 'Auto-updates from Stainless' ``` -This assumes the following secrets have been [uploaded to your GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): - -- `secrets.STAINLESS_API_KEY`: Your Stainless API key. -- `secrets.API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with permissions to push to your docs repo. +Required GitHub Secrets: +- `STAINLESS_API_KEY`: Your Stainless API key +- `API_TOKEN_GITHUB`: GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with docs repo access \ No newline at end of file diff --git a/migration.mdx b/migration.mdx index 491e89454..068c008f5 100644 --- a/migration.mdx +++ b/migration.mdx @@ -4,141 +4,48 @@ description: 'How to migrate documentation from your existing provider' icon: 'arrow-up-from-bracket' --- -You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to scrape documentation frameworks to Mintlify. +## Supported Platforms -We currently support migration for: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +We support migrating documentation from: - - - - - - - - - - - -} /> - - -} /> - - -} /> + + } /> + } /> + } /> -Don't see your docs provider or have a home grown system? We can still help! Please get in touch at sales@mintlify.com. - -## Commands +Don't see your docs provider? Contact us at sales@mintlify.com for custom migration support. -- `mintlify-scrape section [url]` - Scrapes multiple pages in a site. -- `mintlify-scrape page [url]` - Scrapes a single page in a site. +## Installation +Install the migration package: -The commands will automatically detect the framework. - -## 🚀 Installation - -First, install the package: - -``` +```bash npm i @mintlify/scraping ``` -One-time use: - -```bash Section -npx @mintlify/scraping@latest section [url] -``` - -```bash Page -npx @mintlify/scraping@latest page [url] -``` - - -Global installation: - -``` -npm install @mintlify/scraping@latest -g -``` +## Usage -Global usage: +Use one of these commands to migrate your docs: -```bash Section +```bash Full Section mintlify-scrape section [url] ``` -```bash Page +```bash Single Page mintlify-scrape page [url] ``` -Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. +The scraper will automatically detect which platform you're migrating from. +For OpenAPI/Swagger files, use: +```bash +mintlify-scrape openapi-file [filename] ``` -mintlify-scrape openapi-file [openApiFilename] --w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true] --o, --outDir The folder in which to write any created frontmatter files [string] -``` \ No newline at end of file +Options: +- `-w, --writeFiles`: Write frontmatter files (default: true) +- `-o, --outDir`: Output directory for generated files \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..835021880 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -17,170 +17,64 @@ 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 - `mint.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 `mint.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 `mint.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 `mint.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). +Follow these simple steps to create and deploy your documentation with Mintlify. + +### 1. Create Your Docs Repository + +Get started by either: +- Using our [dashboard](https://dashboard.mintlify.com) to create your documentation +- Cloning our [starter kit](https://github.com/mintlify/starter) repository + +### 2. Set Up Your Environment + +1. Install the Mintlify CLI: +```bash +npm i -g mintlify +``` + +2. Clone your docs repository: +```bash +git clone +``` + +### 3. Customize Your Docs + +1. **Basic Configuration**: Update your `mint.json` file with your brand details: +```json +{ + "name": "Your Company", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "colors": { + "primary": "#2AB673" + } +} +``` + +2. **Add Content**: Create new pages using MDX files with this template: +```md +--- +title: "Page Title" +description: "Description of your page" +--- +``` - +### 4. Preview and Deploy - +1. Preview locally: +```bash +mintlify dev +``` - 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). +2. Push your changes to GitHub to automatically deploy your updates. - We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). +### Need Help? - - +- Join our [community](https://mintlify.com/community) +- Email us at [support@mintlify.com](mailto:support@mintlify.com) - 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). - - -### Publishing - - - -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://www.dashboard.mintlify.com/settings) to add a custom domain. - -![Custom Domain](/images/custom-domain.png) - - - -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). + Want a hands-off approach? Our Enterprise plan includes white-glove migration services. [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 350cb3c18..ec747fa47 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -1,808 +1 @@ ---- -title: "Global Settings" -description: "Customize your documentation using the mint.json file" -icon: "wrench" ---- - -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: - -```json -"font": { - "headings": { - "family": "Roboto" - }, - "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](/settings/versioning). - -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" - }, - { - "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" } - ] - }, - { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] - } - ] -} -``` - - - - 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" - } - } - ``` - - -## More Customization - -Learn more about how to further customize your docs with custom CSS and JS in -[Custom Scripts](https://mintlify.com/docs/advanced/custom/). +null \ No newline at end of file