diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bc24fbbf6..56aa0fd3e 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -3,25 +3,34 @@ title: "OpenAPI Setup" description: "Reference OpenAPI endpoints in your docs pages" --- -## Add an OpenAPI specification file +## Adding Your OpenAPI Spec -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+. +### Format Requirements +Make sure your OpenAPI document follows these requirements: +- Valid JSON or YAML format +- Follows OpenAPI specification 3.0+ +- Contains complete endpoint and schema definitions -## Auto-populate API pages +### Validating Your Spec +Before proceeding, validate your OpenAPI spec using our CLI tool: -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.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/anchor. +```bash +mintlify openapi-check +``` + +## Auto-Generation Options -**Example with Anchors:** +You have two main options for automatically generating API documentation from your OpenAPI spec: + +### Using Anchors +Add the OpenAPI spec to an anchor in your `mint.json` to generate pages under that section: ```json {5} { "anchors": [ { "name": "API Reference", - "openapi": "/path/to/openapi.json", + "openapi": "/path/to/openapi.json", // Local path or URL "url": "api-reference", "icon": "square-terminal" } @@ -29,9 +38,12 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -![](/images/anchors-autogeneration-anchors.png) + + OpenAPI Anchor Generation Example + -**Example with Tabs:** +### Using Tabs +Alternatively, add the spec to a tab to organize the generated pages under that tab: ```json {6} { @@ -45,108 +57,75 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -![](/images/autogeneration-with-tabs.png) - -To validate your OpenAPI spec, you can use this command:
`mintlify openapi-check ` - - -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. + + OpenAPI Tab Generation Example + -* `version`: The `version` value from the anchor or tab, if present. +### Generated Page Metadata +Auto-generated pages will include the following metadata by default: -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. +- **Title**: Uses the OpenAPI operation's `summary` field, or generates one from the HTTP method and endpoint +- **Description**: Uses the OpenAPI operation's `description` field if present +- **Version**: Inherits the `version` from the parent anchor or tab if specified -## Create MDX files for API pages +## Custom MDX 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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). +For more control over your API documentation, you can create individual MDX pages for each operation. -![](/images/elevenlabs-mdx-autogeneration-example.png) +### Why Create Custom Pages? +Custom MDX pages allow you to: +- Customize page metadata +- Add supplementary content and examples +- Control which operations to include +- Organize pages in a custom order -### 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. Use the relative path to the -OpenAPI document in your codebase. +### Using the Scraper +For large APIs, manually creating pages can be time-consuming. Use our scraper tool to automate this process: ```bash +# Basic usage npx @mintlify/scraping@latest openapi-file -``` - -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 +# Specify output directory npx @mintlify/scraping@latest openapi-file -o api-reference ``` -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. + The scraper requires a valid OpenAPI document. Invalid specs will cause the generation to fail. -### 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. +### Manual Page Creation +You can also create pages manually by referencing OpenAPI operations in your page metadata: - ```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 - --- - ``` - +```md Single OpenAPI File +--- +title: "Get Users" +openapi: "GET /users" +--- +``` -
+```md Multiple OpenAPI Files +--- +title: "Get Users" +openapi: "/path/to/openapi-1.json GET /users" +--- +``` + - 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. + The method and path must exactly match your OpenAPI specification. Mismatches will result in empty pages. -## Create MDX files for OpenAPI schemas +## Schema Documentation -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: +### Creating Schema Pages +Generate standalone pages for your OpenAPI schemas defined in `components.schemas`: - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` - - ```md Format - --- - openapi-schema: "schema-key" - --- - ``` - \ No newline at end of file +```md +--- +openapi-schema: "OrderItem" +--- +``` + +This automatically creates a page documenting the structure and properties of your schema. \ No newline at end of file diff --git a/development.mdx b/development.mdx index 856629aaf..3992d46eb 100644 --- a/development.mdx +++ b/development.mdx @@ -3,13 +3,17 @@ title: 'Local Development' description: 'Preview changes locally to update your docs' --- +## Prerequisites + +Please make sure you have **Node.js version 19 or higher** installed before proceeding with the setup. + -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. +## Installation - +### Installing Mintlify CLI -**Step 1**: Install Mintlify: +You can install Mintlify globally on your system using your preferred package manager: @@ -27,13 +31,9 @@ description: 'Preview changes locally to update your docs' -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: - -```bash -mintlify dev -``` +### Alternative Installation -Alternatively, if you do not want to install Mintlify globally you can use a run script available: +If you prefer not to install Mintlify globally, you can use it directly through package manager execution commands: ```bash npm @@ -51,31 +51,47 @@ Alternatively, if you do not want to install Mintlify globally you can use a run - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. +If you're using Yarn's "dlx" command, note that it requires Yarn version >2. Learn more about dlx [here](https://yarnpkg.com/cli/dlx). -A local preview of your documentation will be available at `http://localhost:3000`. +## Running Locally + +### Starting the Development Server + +1. Navigate to your docs directory (where the `mint.json` file is located) +2. Run the following command: + +```bash +mintlify dev +``` + +Your documentation preview will be available at `http://localhost:3000`. -### Custom Ports +### Port Configuration -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +#### Default Port + +By default, Mintlify runs on port 3000. You can customize this using the `--port` flag: ```bash mintlify dev --port 3333 ``` -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: +#### Port Conflicts + +If your specified port is already in use, Mintlify will automatically try the next available port: -```md +```bash Port 3000 is already in use. Trying 3001 instead. ``` -## Mintlify Versions +## Maintenance -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: +### Version Management - +The CLI version needs to match Mintlify's platform version. If you notice discrepancies between local and production previews, update your CLI: + ```bash npm npm i -g mintlify@latest ``` @@ -87,45 +103,59 @@ Please note that each CLI release is associated with a specific version of Mintl ```bash pnpm pnpm up --global mintlify ``` - -## Validating Links +### Link Validation -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +Check for broken references in your documentation using: ```bash mintlify broken-links ``` -## Deployment +## Development Tools + +### Code Editor Setup -If the deployment is successful, you should see the following: +For the best development experience, we recommend: + +1. [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting +2. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting + +### Deployment Verification + +After a successful deployment, you should see a confirmation screen: Deployment success screen showing all checks passed -## 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` + + If you encounter the error: "Could not load the sharp module using the darwin-arm64 runtime", follow these steps: + + 1. Remove existing Mintlify installation: + ```bash + npm remove -g mintlify + ``` + 2. Upgrade Node.js to v19 or higher + 3. Reinstall Mintlify: + ```bash + npm install -g mintlify + ``` - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + For unexpected errors: + + 1. Navigate to your device's root directory + 2. Delete the ~/.mintlify folder + 3. Run `mintlify dev` again - + \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..f116252b8 100644 --- a/mint.json +++ b/mint.json @@ -65,12 +65,17 @@ "icon": "pen-paintbrush", "pages": [ "development", + "web-editor", + "quickstart", "web-editor" ] }, "settings/global", "settings/navigation", - "migration" + "migration", + "development", + "settings/navigation", + "settings/global" ] }, { @@ -94,7 +99,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" ] }, { diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..53d738289 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,6 +4,8 @@ description: "Start building modern documentation in under five minutes" icon: "rocket" --- +## Introduction + -## Getting Started +Welcome to Mintlify! This guide will walk you through deploying your documentation and making it shine. We'll cover initial setup, content updates, and deployment steps. + +## Repository Setup -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +### Create Your Documentation Repository -### Creating the Repository +Mintlify renders documentation from MDX files using configurations in our [starter kit](https://github.com/mintlify/starter). You can begin by either: -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. +1. Onboarding through the [dashboard](https://dashboard.mintlify.com) +2. Cloning our [starter kit](https://github.com/mintlify/starter) repository - +### Connect with GitHub - - - 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. + + Follow these steps to enable automatic deployments: - - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - + 1. Visit your [dashboard settings](https://dashboard.mintlify.com/settings) + 2. Find and click the GitHub app installation link + 3. Complete the installation process + 4. Verify success - you'll see a check mark next to your repository's commit hash + + + ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) + + - +### Repository Structure Options - 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) + To include documentation within your codebase: + + 1. Move your docs content into your monorepo + 2. Update the path to your `mint.json` in the [dashboard settings](https://dashboard.mintlify.com/settings/deployment/git-settings) + Monorepo setup - +## Content Management -### Updating the Content +You have multiple options for updating your documentation content. Choose the method that best fits your workflow. -Mintlify enables you to easily customize the style, structure, and content of -your docs. +### Development Environments - - + + Set up your local environment: - 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`. + 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + 2. Clone your repository: `git clone ` + 3. Open the repository in your preferred IDE + 4. Install our preview tool: `npm i -g mintlify` - Learn more about this in our [local development guide](/development). - - - - + For detailed instructions, see our [local development guide](/development). + - Learn more about how to use the web editor on our [guide](/web-editor). + + For a more visual editing experience, try our web editor. Learn how to use it in our [web editor guide](/web-editor). + - +### Customization - - - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: + + Update your `mint.json` file with your brand elements: - ```json - "name": "Your Company" + ```json Basic Configuration + { + "name": "Your Company", "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg", @@ -97,90 +103,102 @@ your docs. "colors": { "primary": "#2AB673", "light": "#55D799", - "dark": "#117866", - }, - ``` + "dark": "#117866" + } + } + ``` - A full list of supported configurations can be found at [global settings](/settings/global). + Find all available options in our [global settings](/settings/global) guide. + - +### Content Creation - + + Create new pages using this basic template: - Add content with simple MDX files. Initiate your pages with this template: + ```md Page Template + --- + title: "Page Title" + sidebarTitle: "Sidebar title (optional)" + description: "Brief description" + --- + ``` - ```md - --- - title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" - --- - ``` + Learn more about: + - [MDX syntax](/text) for formatting + - [Component library](/content/components) for enhanced features + - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). +### Deployment Process - + + Deploy your changes by: - + 1. Committing your updates + 2. Pushing to your repository - 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). + If the GitHub app deployment fails, you can manually update through the [dashboard](https://dashboard.mintlify.com). - - ![Manual - Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) - + + ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) + + + +### API Documentation - + + Configure API documentation using OpenAPI: - + 1. Add your OpenAPI specification: + ```json + "openapi": "link-to-your-openapi-file" + ``` - You can easily set up your API references using an OpenAPI document. + 2. Generate endpoint files: + ```bash + npx @mintlify/scraping@latest openapi-file + ``` - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL. + 3. Add generated files to `mint.json` navigation - ```json - "openapi": "link-to-your-openapi-file" - ``` + Resources: + - [OpenAPI setup guide](/api-playground/openapi/setup) + - [Authentication configuration](/api-playground/openapi/writing-openapi) + - [Manual API documentation](/api-playground/overview) + - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: +### Analytics Integration - ```bash - npx @mintlify/scraping@latest openapi-file - ``` + + Track documentation usage with: - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. + - Built-in analytics on your [dashboard](https://dashboard.mintlify.com/analytics) + - Third-party [analytics providers](/integrations/analytics/overview) + - 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). +## Publication - +### Domain Configuration - + + Host documentation on your domain: - 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). + 1. Access your [dashboard settings](https://www.dashboard.mintlify.com/settings) + 2. Navigate to domain settings + 3. Add your custom domain - We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). + ![Custom Domain](/images/custom-domain.png) + - - +### Enterprise Support - 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). + Need help migrating? Our Enterprise plan includes white-glove migration services. Contact us at [sales@mintlify.com](mailto:sales@mintlify.com) to learn more. -### Publishing - - - -Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan. +## Support -Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain. - -![Custom Domain](/images/custom-domain.png) - - +Your documentation is now ready! If you need assistance: -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). +- 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 350cb3c18..601585ed6 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -4,119 +4,119 @@ 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) +## Overview -## Properties +Every Mintlify site needs a `mint.json` file with the core configuration settings. This file controls everything from your site's appearance to its navigation structure and integrations. -### Styling +## Basic Properties + +Let's start with the essential configuration options that every site needs. + +### Site Identity - Name of your company or project. Used for the global title. + Name of your company or project. This is used for the global title that appears in browsers and search results. +### Logo Configuration + - 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. + Configure your site's logo for both light and dark modes. SVG format is recommended for crisp display at any size. - Path to the logo in light mode. For example: `/path/to/logo.svg` + Path to your light mode logo. Example: `/logo/light.svg` - Path to the logo in dark mode. For example: `/path/to/logo.svg` + Path to your dark mode logo. Example: `/logo/dark.svg` - Where clicking on the logo links you to + URL that users go to when clicking your logo - - Path to the favicon image. For example: `/path/to/favicon.svg` + Path to your site's favicon image. Example: `/favicon.svg` +## Visual Styling + +Configure the look and feel of your documentation site. + +### Color Scheme + - Hex color codes for your global theme + Define the hex color codes for your global theme. - The primary color. Used most often for highlighted content, section - headers, accents, in light mode + Main color used for highlights, headers, and accents in light mode - The primary color for dark mode. Used most often for highlighted content, - section headers, accents, in dark mode + Primary color used in dark mode for highlights and accents - The primary color for important buttons + Color used for important buttons and elements - The color of the background in both light and dark mode + Background colors for light and dark modes - The hex color code of the background in light mode + Background color in light mode - The hex color code of the background in dark mode + Background color in dark mode - +### Theme and Layout + - 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) + Choose from our preset theme 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 the global layout style of your documentation. +### Background Elements + - Set a decorative background. + Add decorative background elements to your site. - The style of the decorative background. + Choose a decorative background style - Set a custom background image to be displayed behind every page. + Set a custom background image that appears behind all pages - - Custom fonts. Apply globally or set different fonts for headings and the body - text. +### Typography -Example: + + Customize your site's fonts globally or set different fonts for headings and body text. +Example: ```json "font": { "headings": { @@ -130,592 +130,182 @@ Example: - The font family name. Custom fonts and all [Google - Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans", - "Playfair Display" + Font family name. Supports both [Google Fonts](https://fonts.google.com/) and custom fonts. - 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. + Font weight (supports variable fonts with precise values) - The URL to the font file. Can be used to specify a font that is not from - Google Fonts. + URL to your custom font file - The font format. Required if using a custom font source (`url`). + Required when using a custom font via URL - - - Customize the dark mode toggle. +## Navigation Structure - - - 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. - +Control how users navigate your documentation. - - 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 +### Primary Navigation - An array of groups with all the pages within that group + Define the structure of your sidebar navigation. - The name of the group. + Section heading in the sidebar - 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. + List of paths to your documentation files - The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders. + [Fontawesome](https://fontawesome.com/icons) icon for sub-folders - The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin + Icon style: brands, duotone, light, sharp-solid, solid, or thin - +### Additional Navigation Elements + - Array of names and urls of links you want to include in the topbar + Add links to your topbar navigation. - The name of the button. + Link text - The url once you click on the button. Example: `https://mintlify.com/contact` + Destination URL - + Configure the main call-to-action button in your topbar. + - Link shows a button. GitHub shows the repo information at the url provided - including the number of GitHub stars. + Choose between a standard link or GitHub stats display - If type is a link: What the button links to. If type is a github: Link to - the repository to load GitHub information from. + Button destination URL - Text inside the button. Only required if type is a link. + Button text (for link type) - The style of the button. + Button shape - 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. + Show/hide the arrow icon - - - 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. - -{" "} - - - -{" "} - - +## Advanced Features - - - 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. - +### Versioning and Localization - - 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. + + Enable documentation versioning or localization. [Learn more](/settings/versioning) 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 Versions + "versions": ["v1.0", "v1.1"] + ``` -```json -"footer": { - "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" }, - "links": [ + ```json Localization + "versions": [ { - "title": "Column 1", - "links": [ - { "label": "Column 1 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 1 Link 2", "url": "https://mintlify.com" } - ] + "name": "English", + "locale": "en", }, { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] + "name": "Español", + "locale": "es" } ] -} -``` - - - - 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. - + + + Version name or language display name - - Enables a button to allow users to raise an issue about the documentation + + Language code for localization - - - - - Configurations to change the search prompt - - - - Set the prompt for the search bar. Default is `Search...` + + Set as default version -### API Configurations +### API Integration - Configuration for API settings. Learn more about API pages at [API Components](/api-playground). + Configure API documentation settings. [Learn more](/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`. - - + Base URL for API endpoints - 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. + + Control API playground visibility - - - 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) + Add third-party integrations - Enables Intercom widget on docs site. The value should be your Intercom App ID. + Intercom App ID - Enables Frontchat widget on docs site. The value should be your Frontchat App ID. + 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` - +### Analytics and SEO - + + Configure analytics integrations. See [supported platforms](/integrations/analytics/overview). -### Search Engine Optimization - - Settings for Search Engine Optimization. + Search engine optimization settings. Example: - ```json "seo": { "indexHiddenPages": true @@ -724,85 +314,61 @@ Example: - Enables indexing pages not included in `navigation`. + Allow indexing of pages not in navigation -## Example `mint.json` +## Example Configuration -Click on the following dropdown to view a sample configuration file +Want to see it all together? Check out this complete example: - - ```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" + +```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" + } + ], + "navigation": [ + { + "group": "Getting Started", + "pages": ["introduction", "quickstart"] } + ], + "footerSocials": { + "github": "https://github.com/mintlify", + "x": "https://x.com/mintlify" } - ``` +} +``` -## More Customization +## Further Customization -Learn more about how to further customize your docs with custom CSS and JS in -[Custom Scripts](https://mintlify.com/docs/advanced/custom/). +Need even more customization options? Learn how to add custom CSS and JavaScript in our [Custom Scripts guide](https://mintlify.com/docs/advanced/custom/). \ No newline at end of file diff --git a/settings/navigation.mdx b/settings/navigation.mdx index ec1ab6e76..53a4764dc 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -1,25 +1,25 @@ --- title: "Navigation" -description: "Organize your docs directory to guide your users to the information they need " +description: "Organize your docs directory to guide your users to the information they need" icon: "map" --- -## Tabs +## Navigation Components -Tabs help distinguish between different topics or sections of your -documentation. They show up above the main sidebar. +The navigation system in Mintlify consists of several key components that help organize your documentation structure. Let's explore each component and how to configure them effectively. + +### Tabs Overview +Tabs provide a high-level way to separate different sections of your documentation. They appear prominently above the main sidebar, making them perfect for distinguishing between major documentation categories. - -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of -the tab object should map to a folder of content added to your sidebar, or an -external link. +### Configuring Tabs +Add tabs using the `tabs` field in your `mint.json` file. Each tab can either link to a content folder or an external URL. -```json +```json Basic Tab Configuration "tabs": [ { "name": "API References", @@ -28,7 +28,14 @@ external link. { "name": "Content", "url": "content" - }, + } +] +``` + +For external links, simply use the complete URL: + +```json Tab with External Link +"tabs": [ { "name": "Blog", "url": "https://your-website.com/blog" @@ -36,33 +43,29 @@ external link. ] ``` -To configure the default `Documentation` primary tab, add the `primaryTab` field -to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. +### Primary Tab Settings +The default "Documentation" tab can be customized by adding the `primaryTab` field to your `mint.json`: -```json +```json Primary Tab Configuration "primaryTab": { "name": "Home" } ``` -## Anchors +## Using Anchors -Anchors provide another way to direct users to sections of your documentation, -or link out to external URLs. +### Anchor Overview +Anchors offer another navigation option for your documentation. They can direct users to specific documentation sections or external resources. - -Configure anchors with the `anchors` field of the `mint.json` file. The `url` -field of the tab object should map an external link, or a folder of content -added to your sidebar. More fields for anchors can be found -[here](/settings/global). +### Anchor Configuration +Configure anchors in your `mint.json` file using the `anchors` field: -```json +```json Basic Anchor Configuration "anchors": [ { "name": "API References", @@ -73,7 +76,14 @@ added to your sidebar. More fields for anchors can be found "name": "Content", "icon": "pencil", "url": "content" - }, + } +] +``` + +For external links in anchors: + +```json Anchor with External Link +"anchors": [ { "name": "Contact us", "icon": "envelope", @@ -82,27 +92,26 @@ added to your sidebar. More fields for anchors can be found ] ``` -To configure the default `Documentation` top anchor, add the `topAnchor` field -to your `mint.json`. +### Default Anchor Customization +Customize the default "Documentation" anchor using the `topAnchor` field: -```json +```json Top Anchor Configuration "topAnchor": { "name": "Home", "icon": "building" } ``` -## Sidebar +## Sidebar Navigation -Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) +### Basic Structure +The sidebar is configured through the `navigation` property in your `mint.json`. Files are organized into groups for better structure. - Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. + You must explicitly add pages to your `mint.json` to make them appear in the sidebar. Adding a file to your docs directory alone won't make it show up automatically. -```json Regular Navigation +```json Basic Sidebar Structure "navigation": [ { "group": "Getting Started", @@ -111,11 +120,10 @@ mint.json, You don't need to include `.mdx` in page names. For sidebar styling o ] ``` -### Groups +### Nested Groups +Create deeper navigation structures by nesting groups within groups: -Create groups by recursively nesting a group within a group. - -```json Nested Navigation +```json Nested Navigation Structure "navigation": [ { "group": "Getting Started", @@ -130,109 +138,88 @@ Create groups by recursively nesting a group within a group. ] ``` -### Folders - -Simply put your MDX files in folders and update the paths in `mint.json`. +### Working with Folders -For example, to have a page at `https://yoursite.com/your-folder/your-page` you -would make a folder called `your-folder` containing an MDX file called -`your-page.mdx`. +#### Basic Folder Organization +Organize your content by placing MDX files in folders and referencing their paths in `mint.json`. - You cannot use `api` for the name of a folder unless you nest it inside - another folder. Mintlify uses Next.js which reserves the top-level `api` - folder for internal server calls. We recommend using the folder name - `api-reference` instead. + The folder name `api` is reserved at the root level. Use `api-reference` or nest it within another folder instead. - - ```json Navigation With Folder - "navigation": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } - ] - ``` - -```json Nested Navigation +Example folder structure for the URL `https://yoursite.com/your-folder/your-page`: +``` +docs/ + └── your-folder/ + └── your-page.mdx +``` + +Configure this in your navigation: +```json Folder Navigation "navigation": [ { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] + "group": "Group Name", + "pages": ["your-folder/your-page"] } ] ``` - - ### Hidden Pages +Pages not listed in your `mint.json` navigation are hidden from the sidebar but remain accessible via direct links. By default, these pages aren't indexed for search. -MDX files not included in `mint.json` will not show up in the sidebar but are -accessible by linking directly to them. - -Hidden pages are not indexed for search within your docs by default. If you -would like to override this behavior, you can set the -[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute -in your `mint.json` to `true`. - -## Topbar +To include hidden pages in search: +```json Search Configuration +{ + "seo": { + "indexHiddenPages": true + } +} +``` -### Links +## Topbar Configuration -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. +### Adding Links +Enhance your topbar with custom links using the `topbarLinks` field: -The `topbarLinks` field supports the following fields: `name`, `url`. - -```json - "topbarLinks": [ +```json Topbar Links +"topbarLinks": [ { - "name": "Community", - "url": "https://mintlify.com/community" + "name": "Community", + "url": "https://mintlify.com/community" } - ] +] ``` -### CTA Button +### Call-to-Action Button -Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton` -field. +#### Basic CTA +Add a call-to-action button to your topbar: -The `topbarCtaButton` field supports the following fields: `name`, `url`, `type`, `style`, and `arrow`. For more information on the options for these fields, see the [mint.json schema](/settings/global#structure). - -```json - "topbarCtaButton": { +```json Basic CTA Button +"topbarCtaButton": { "name": "Get Started", "url": "https://mintlify.com/get-started" - } +} ``` -#### GitHub - -You can also configure the CTA button to link directly to your GitHub -repository. Use the `topbarCtaButton` field with the `type` set to `github`. +#### GitHub Integration +Link directly to your GitHub repository: -```json - "topbarCtaButton": { +```json GitHub CTA Configuration +"topbarCtaButton": { "type": "github", "url": "https://github.com/mintlify/docs" - } -``` +} +``` \ No newline at end of file diff --git a/web-editor.mdx b/web-editor.mdx index 0c945d94b..ef9b9f8c2 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -1,143 +1,137 @@ --- title: 'Web Editor' -description: 'Edit your docs directly from the dashboard with live previews.' +description: 'Edit your docs directly from the dashboard with live previews' --- -Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. +The Web Editor provides an intuitive interface to edit your docs directly through the dashboard without needing to open your IDE or run the development server. Let's explore its key features and how to use them effectively. -The editor includes a few key features to integrate directly into your existing git workflow, -like creating branches, pull requests, commits, and diffs for your current changes. +## Core Features -It also includes a fully editable experience for changing and adding content directly, -even with custom components. +The editor comes with several powerful capabilities: -If you understand git workflows and our integrations already, you can skip to [here](#editing-content). +- Live preview as you edit content +- Git workflow integration for branches and PRs +- Visual and source code editing modes +- Direct file creation and editing +- Image upload and management +- Component insertion via slash commands -## Git and update workflows +If you're already familiar with git workflows and our integrations, feel free to skip to the [Editing Content](#editing-content) section. -### Git basics +## Understanding Git Workflows -While Web Editor means you don't need to go to GitHub or your command line to make -changes, it's still helpful to know the basics of git. +### Key Git Concepts -Git terminology: +Before diving into the editor features, here are some essential git terms to know: -- **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub). +- **Repository**: Your code's storage location, either local (on your computer) or remote (like GitHub) +- **Branch**: A separate development line for working on changes safely +- **Commit**: A snapshot of your file changes +- **Pull Request**: A request to merge your branch's changes into the main branch -- **Commit**: A snapshot of changes made to files in the repository. +### Setting Up GitHub Integration -- **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version. + + Before making updates, install the Mintlify GitHub app. You can do this through the [GitHub App settings](https://dashboard.mintlify.com/settings/organization/github-app) or follow our [deployment documentation](#1-deploying-your-docs-repository). + -- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. +## Working with Branches -### Making updates +### Creating New Branches -In order to make updates to your docs, we include a few buttons specifically to -integrate with your git workflow. +When making changes, it's best practice to work in a separate branch rather than directly in main. Here's how to create and manage branches: - - If you haven't done so already, please install the Mintlify GitHub app to your GitHub account. - You can find [documentation here](#1-deploying-your-docs-repository), or you can install - the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) - page of the dashboard. - +1. Click the branch selector in the top left of the editor +2. Choose "New Branch" from the modal - - - In order to make changes to your docs, you might want to change from the main branch - to avoid publishing directly to your main docs site. + + + + - To do this, you can open the branches modal on the top left of the editor. +### Branch Creation Modal - - - - +The branch creation modal lets you: +- Name your new branch +- Choose the base branch to branch from +- Add an optional description - From here, you can either switch to a different git branch than `main`, or you can - create a new branch by clicking the **"New Branch"** button. + + + + - - - - + + Always create a new branch for changes to enable team review via pull requests. Some repositories may restrict direct main branch changes. + - After you create a new branch, you'll automatically be switched, and all changes - you make will be made to this new branch until you change branches again or reload the page. +### Branch Switching - By default, when you load the page again, you'll default to the main branch. +After creating a branch: +- Your editor automatically switches to the new branch +- Changes are saved to this branch until you switch or reload +- Reloading defaults back to the main branch - - As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you. - - +## Making Changes - - In order to make a commit, you have two options, both of which appear on the top - right of the editor: +### Committing to Main Branch - - - If you're on the main branch of your docs repository, you can push a commit - directly to the repo by clicking the **"Publish"** button. You'll see your changes - reflect in your git branch the next time you run `git pull`. +When working directly on main: - - - - - +1. Make your desired changes +2. Click the "Publish" button in the top right +3. Your changes will be pushed directly to the repository - - If you're not on the main branch, you can push a commit to your branch by clicking - on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch - up for review, you can click the **"Publish Pull Request"** button. + + + + - - - - - - +### Committing to Other Branches - This will create the pull request for you on GitHub using the branch you selected onto - your main branch. - +When working on a feature branch: - - If you do put your pull request up for review, you can edit the title and description - of the PR, but a default Mintlify title will be provided for you if you leave it - empty. +1. Click "Save Changes" to commit to your branch +2. Use "Publish Pull Request" when ready for review - - - - - - + + + + -## Editing content +### Creating Pull Requests -### Slash commands +The pull request modal allows you to: +- Set a custom title (or use the auto-generated one) +- Add a descriptive message +- Select target branch for merging -The easiest way to add content in the editor is by using **"Slash commands"**, which are -commands you have access to after typing `/` in the **"Visual Editor"** mode: + + + + + +## Editing Content + +### Using Slash Commands + +The quickest way to add content is through slash commands in Visual Editor mode. Type `/` to see available options: -As you type, you'll see more options pop up: +The command menu filters as you type: -#### Content blocks +### Available Content Blocks -Here are the types of content blocks available to add in the **"Visual Editor"**: +The Visual Editor supports various content blocks through slash commands: @@ -169,113 +163,121 @@ Here are the types of content blocks available to add in the **"Visual Editor"** -### Adding images +## Working with Images + +### Adding New Images -You can add images to your page by typing `/image` and either clicking on the **"Image"** -option or hitting ↓ + Enter on the **"Image"** option. +To insert an image: -This will open up the image modal where you have the option to either upload a new -image or use an existing image from the repo. +1. Type `/image` or use ↓ + Enter on the Image option +2. Choose to upload new image or select existing one +3. Preview and confirm selection -Uploading an image can be done through the modal: +### Image Upload Interface + +The upload modal provides a simple drag-and-drop interface: -And you can preview an existing image before you add it. +### Image Preview + +Before inserting, you can preview existing images: -### Editing images +### Editing Existing Images + +To modify images already in your content: -In order to edit images, you just have to hover over the image to see the **"Delete"** -and **"Edit"** buttons on the top right of the image. +1. Hover over the image to reveal controls +2. Use Delete or Edit buttons in top right +3. Adjust image attributes in the edit modal -Clicking the **"Edit"** button lets you edit the attributes of the image. +### Image Attributes + +The edit modal lets you modify: -If you want to update the source of an image to be a new image that you haven't yet -uploaded, you have to first delete the image you're changing, and then add a new one -using the [instructions above](#adding-images). +To replace an image with a new upload: +1. Delete the existing image +2. Add new image following the [Adding New Images](#adding-new-images) process -## Editor modes +## Editor Modes -In order to offer the most flexibility, the editor has three modes: +The editor offers three distinct modes for different needs: -### Visual Editor - -The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion. -It offers you a view into your docs in a fully editable way that reflects what the final -page would look like on your main docs site. - -### Source Editor - -The **"Source Editor"** offers you a way to edit your MDX files in code, the same way -you'd do in your IDE. This offers less flexibility, in that our components aren't available -for auto-complete, but it does have two unique advantages. +### Visual Editor Mode -1. It allows you to edit props of components (see our [limitations below](#current-limitations)) -which is currently not available in **"Visual Editor"** mode yet. +The Visual Editor provides a WYSIWYG interface similar to Notion: +- Real-time preview of content +- Visual component editing +- Slash command support +- Drag-and-drop functionality -2. It allows you to correct syntax errors which might've appeared in your repo that -might not be compatible with **"Visual Editor"** mode until you've fixed them. +### Source Editor Mode -### Diff View +The Source Editor lets you work directly with MDX code: +- Direct access to component props +- Manual syntax error correction +- Code-level content editing +- Raw markdown editing -The **"Diff View"** is a way to view the changes made to a specific document before -committing it to your repository. +### Diff View Mode -This will help you see changes you've made along with formatting changes made by -the editor. +The Diff View helps track changes: +- Side-by-side change comparison +- Highlighted additions/deletions +- Format change visibility +- Pre-commit review capability -## Current limitations +## Current Limitations -We do have a few current limitations in the editor that we're working to resolve. +We're actively working to resolve these current limitations: - You currently cannot live-update your navigation based on added/edited files. You - still have to manually edit renamed, added, and deleted files in your `mint.json` + Manual `mint.json` edits still required for navigation changes. - We currently don't show any previews for custom snippets. This is on our roadmap to support - as fully editable components. + Full snippet editing support coming soon. - We currently don't show any previews for OpenAPI specs. This is on our roadmap to support - as a read-only preview. + Read-only OpenAPI preview support in development. ## Feedback -If you have any bug reports, feature requests, or other general feedback, we'd love to hear -where we can improve. +We value your input on improving the editor. Share your: +- Bug reports +- Feature requests +- General feedback -Email us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file +Contact us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file