diff --git a/docs.json b/docs.json index e364b4726..23aa1c9be 100644 --- a/docs.json +++ b/docs.json @@ -12,265 +12,297 @@ "library": "lucide" }, "navigation": { - "tabs": [ + "versions": [ { - "tab": "Documentation", - "groups": [ + "version": "2.0", + "tabs": [ { - "group": "Getting started", - "pages": [ - "index", - "quickstart", - "installation", + "tab": "Documentation", + "groups": [ { - "group": "Web editor", - "icon": "mouse-pointer-2", + "group": "Getting started", "pages": [ - "editor/getting-started", - "editor/git-concepts", - "editor/branches", - "editor/content-management", - "editor/publishing", - "editor/keyboard-shortcuts", - "editor/troubleshooting" + "v2/index", + "v2/quickstart", + "v2/installation" + ] + }, + { + "group": "Core configuration", + "pages": [ + "v2/settings", + "v2/pages", + "v2/navigation", + "v2/themes" ] } ] - }, - { - "group": "Core configuration", - "pages": [ - "settings", - "pages", - "navigation", - "themes", - "settings/custom-domain" - ] - }, - { - "group": "AI optimization", - "pages": [ - "guides/assistant", - "ai/llmstxt", - "ai/contextual-menu", - "ai/model-context-protocol", - "ai/markdown-export", - "guides/geo", - "guides/claude-code", - "guides/cursor", - "guides/windsurf", - "ai/slack-app" - ] - }, - { - "group": "Components", - "pages": [ - "text", - "image-embeds", - "list-table", - "code", - "reusable-snippets", - "components/accordions", - "components/callouts", - "components/cards", - "components/columns", - "components/code-groups", - "components/examples", - "components/expandables", - "components/fields", - "components/frames", - "components/icons", - "components/mermaid-diagrams", - "components/panel", - "components/steps", - "components/tabs", - "components/tooltips", - "components/update", - "components/banner" - ] - }, + } + ] + }, + { + "version": "1.0", + "tabs": [ { - "group": "API pages", - "pages": [ - "api-playground/overview", - "api-playground/openapi-setup", - "api-playground/migrating-from-mdx", + "tab": "Documentation", + "groups": [ { - "group": "Customization", - "icon": "wrench", + "group": "Getting started", "pages": [ - "api-playground/customization/complex-data-types", - "api-playground/customization/adding-sdk-examples", - "api-playground/customization/managing-page-visibility", - "api-playground/customization/multiple-responses" + "index", + "quickstart", + "installation", + { + "group": "Web editor", + "icon": "mouse-pointer-2", + "pages": [ + "editor/getting-started", + "editor/git-concepts", + "editor/branches", + "editor/content-management", + "editor/publishing", + "editor/keyboard-shortcuts", + "editor/troubleshooting" + ] + } ] }, { - "group": "AsyncAPI", - "icon": "webhook", + "group": "Core configuration", "pages": [ - "api-playground/asyncapi/setup", - "api-playground/asyncapi/playground" + "settings", + "pages", + "navigation", + "themes", + "settings/custom-domain" ] }, { - "group": "MDX", - "icon": "markdown", + "group": "AI optimization", "pages": [ - "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "guides/assistant", + "ai/llmstxt", + "ai/contextual-menu", + "ai/model-context-protocol", + "ai/markdown-export", + "guides/geo", + "guides/claude-code", + "guides/cursor", + "guides/windsurf", + "ai/slack-app" ] }, - "api-playground/troubleshooting" - ] - }, - { - "group": "Authentication and personalization", - "pages": [ - "authentication-personalization/authentication-setup", - "authentication-personalization/personalization-setup" - ] - }, - { - "group": "Guides", - "pages": [ - "guides/migration", { - "group": "Analytics dashboard", - "icon": "chart-line", + "group": "Components", "pages": [ - "analytics/overview", - "analytics/feedback", - "analytics/search", - "analytics/improving-docs" + "text", + "image-embeds", + "list-table", + "code", + "reusable-snippets", + "components/accordions", + "components/callouts", + "components/cards", + "components/columns", + "components/code-groups", + "components/examples", + "components/expandables", + "components/fields", + "components/frames", + "components/icons", + "components/mermaid-diagrams", + "components/panel", + "components/steps", + "components/tabs", + "components/tooltips", + "components/update", + "components/banner" ] }, - "react-components", - "settings/custom-scripts", - "settings/seo", - "guides/changelogs", - "guides/hidden-pages", - "settings/broken-links", - "settings/custom-404-page", - "guides/monorepo", { - "group": "Custom Subdirectory", - "icon": "folder", + "group": "API pages", "pages": [ - "advanced/subpath/cloudflare", - "advanced/subpath/route53-cloudfront", - "advanced/subpath/vercel", - "guides/csp-configuration" + "api-playground/overview", + "api-playground/openapi-setup", + "api-playground/migrating-from-mdx", + { + "group": "Customization", + "icon": "wrench", + "pages": [ + "api-playground/customization/complex-data-types", + "api-playground/customization/adding-sdk-examples", + "api-playground/customization/managing-page-visibility", + "api-playground/customization/multiple-responses" + ] + }, + { + "group": "AsyncAPI", + "icon": "webhook", + "pages": [ + "api-playground/asyncapi/setup", + "api-playground/asyncapi/playground" + ] + }, + { + "group": "MDX", + "icon": "markdown", + "pages": [ + "api-playground/mdx/configuration", + "api-playground/mdx/authentication" + ] + }, + "api-playground/troubleshooting" ] }, { - "group": "Dashboard Access", - "icon": "gauge", + "group": "Authentication and personalization", "pages": [ - "advanced/dashboard/sso", - "advanced/dashboard/permissions", - "advanced/dashboard/roles" + "authentication-personalization/authentication-setup", + "authentication-personalization/personalization-setup" + ] + }, + { + "group": "Guides", + "pages": [ + "guides/migration", + { + "group": "Analytics dashboard", + "icon": "chart-line", + "pages": [ + "analytics/overview", + "analytics/feedback", + "analytics/search", + "analytics/improving-docs" + ] + }, + "react-components", + "settings/custom-scripts", + "settings/seo", + "guides/changelogs", + "guides/hidden-pages", + "settings/broken-links", + "settings/custom-404-page", + "guides/monorepo", + { + "group": "Custom Subdirectory", + "icon": "folder", + "pages": [ + "advanced/subpath/cloudflare", + "advanced/subpath/route53-cloudfront", + "advanced/subpath/vercel", + "guides/csp-configuration" + ] + }, + { + "group": "Dashboard Access", + "icon": "gauge", + "pages": [ + "advanced/dashboard/sso", + "advanced/dashboard/permissions", + "advanced/dashboard/roles" + ] + }, + "guides/deployments", + "contact-support" ] }, - "guides/deployments", - "contact-support" - ] - }, - { - "group": "Integrations", - "pages": [ { - "group": "Analytics", - "icon": "chart-no-axes-combined", + "group": "Integrations", "pages": [ - "integrations/analytics/overview", - "integrations/analytics/amplitude", - "integrations/analytics/clearbit", - "integrations/analytics/fathom", - "integrations/analytics/google-analytics", - "integrations/analytics/google-tag-manager", - "integrations/analytics/heap", - "integrations/analytics/hightouch", - "integrations/analytics/hotjar", - "integrations/analytics/koala", - "integrations/analytics/logrocket", - "integrations/analytics/mixpanel", - "integrations/analytics/pirsch", - "integrations/analytics/plausible", - "integrations/analytics/posthog", - "integrations/analytics/segment" + { + "group": "Analytics", + "icon": "chart-no-axes-combined", + "pages": [ + "integrations/analytics/overview", + "integrations/analytics/amplitude", + "integrations/analytics/clearbit", + "integrations/analytics/fathom", + "integrations/analytics/google-analytics", + "integrations/analytics/google-tag-manager", + "integrations/analytics/heap", + "integrations/analytics/hightouch", + "integrations/analytics/hotjar", + "integrations/analytics/koala", + "integrations/analytics/logrocket", + "integrations/analytics/mixpanel", + "integrations/analytics/pirsch", + "integrations/analytics/plausible", + "integrations/analytics/posthog", + "integrations/analytics/segment" + ] + }, + { + "group": "SDKs", + "icon": "folder-code", + "pages": [ + "integrations/sdks/speakeasy", + "integrations/sdks/stainless" + ] + }, + { + "group": "Support", + "icon": "messages-square", + "pages": [ + "integrations/support/overview", + "integrations/support/intercom", + "integrations/support/front" + ] + }, + { + "group": "Privacy", + "icon": "folder-lock", + "pages": [ + "integrations/privacy/overview", + "integrations/privacy/osano" + ] + } ] }, { - "group": "SDKs", - "icon": "folder-code", + "group": "Version control and CI/CD", + "pages": [ + "settings/github", + "settings/gitlab", + "settings/ci", + "settings/preview-deployments" + ] + } + ] + }, + { + "tab": "API Reference", + "groups": [ + { + "group": "API Reference", "pages": [ - "integrations/sdks/speakeasy", - "integrations/sdks/stainless" + "api-reference/introduction" ] }, { - "group": "Support", - "icon": "messages-square", + "group": "Admin", "pages": [ - "integrations/support/overview", - "integrations/support/intercom", - "integrations/support/front" + "api-reference/update/trigger", + "api-reference/update/status" ] }, { - "group": "Privacy", - "icon": "folder-lock", + "group": "Assistant", "pages": [ - "integrations/privacy/overview", - "integrations/privacy/osano" + "api-reference/assistant/create-assistant-message", + "api-reference/assistant/search" ] } ] }, { - "group": "Version control and CI/CD", - "pages": [ - "settings/github", - "settings/gitlab", - "settings/ci", - "settings/preview-deployments" - ] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "API Reference", - "pages": [ - "api-reference/introduction" - ] - }, - { - "group": "Admin", - "pages": [ - "api-reference/update/trigger", - "api-reference/update/status" - ] - }, - { - "group": "Assistant", - "pages": [ - "api-reference/assistant/create-assistant-message", - "api-reference/assistant/search" - ] - } - ] - }, - { - "tab": "Changelog", - "groups": [ - { - "group": "Changelog", - "pages": [ - "changelog" + "tab": "Changelog", + "groups": [ + { + "group": "Changelog", + "pages": [ + "changelog" + ] + } ] } ] @@ -551,4 +583,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/v2/index.mdx b/v2/index.mdx new file mode 100644 index 000000000..919b18c79 --- /dev/null +++ b/v2/index.mdx @@ -0,0 +1,73 @@ +--- +title: "Introduction" +description: "Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers." +icon: "book-open" +mode: "custom" +--- + +export const HeroCard = ({ filename, title, description, href }) => { + return ( + + + +

+ {title} +

+ {description} + + ); +}; + +
+
+ + +
+ +
+

+ Documentation v2 +

+ +
+ Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers. +
+ +
+ + + + + + + +
+
+
\ No newline at end of file diff --git a/v2/installation.mdx b/v2/installation.mdx new file mode 100644 index 000000000..def3322bf --- /dev/null +++ b/v2/installation.mdx @@ -0,0 +1,190 @@ +--- +title: "CLI installation" +sidebarTitle: "Installation" +description: "Install the CLI to preview and develop your docs locally" +icon: "terminal" +--- + + + + +## Installing the CLI + + + **Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding. + + + + + Run the following command to install the [CLI](https://www.npmjs.com/package/mint): + + + ```bash npm + npm i -g mint + ``` + + ```bash pnpm + pnpm add -g mint + ``` + + + + + Navigate to your docs directory (where your `docs.json` file is located) and execute the following command: + + ```bash + mint dev + ``` + + A local preview of your documentation will be available at `http://localhost:3000`. + + + +Alternatively, if you do not want to install the CLI globally, you can run a one-time script: + +```bash +npx mint dev +``` + +## Updates + +If your local preview is out of sync with what you see on the web in the production version, update your local CLI: + +```bash +mint update +``` + +If this `mint update` command is not available on your local version, re-install the CLI with the latest version: + + + ```bash npm + npm i -g mint@latest + ``` + + ```bash pnpm + pnpm add -g mint@latest + ``` + + +## Custom ports + +By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command: + +```bash +mint dev --port 3333 +``` + +If you attempt to run on a port that is already in use, it will use the next available port: + +```mdx +Port 3000 is already in use. Trying 3001 instead. +``` + +## Previewing as a specific group + +If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the `--group [groupname]` flag. + +For example, if you have a group named `admin`, you can preview as a member of that group with the command: + +```bash +mint dev --group admin +``` + +## Additional commands + +While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation. + +### Finding broken links + +The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: + +```bash +mint broken-links +``` + +### Checking OpenAPI spec + +You can use the CLI to check your OpenAPI file for errors using the following command: + +```bash +mint openapi-check +``` + +You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`). + +### Renaming files + +You can rename and update all references to files using the following command: + +```bash +mint rename +``` + +### Migrating MDX endpoint pages + +You can migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification using the following command: + +```bash +mint migrate-mdx +``` + +This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/v2/api-playground/migrating-from-mdx) for detailed information. + +## Formatting + +While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files. + +If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code 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. + +If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting. + +## Troubleshooting + + + + This may be due to an outdated version of node. Try the following: + + 1. Remove the currently-installed version of the mint CLI: `npm uninstall -g mint` + 2. Upgrade to Node.js. + 3. Reinstall the mint CLI: `npm install -g mint` + + + **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again. + + + This is due to not having the required permissions to globally install node packages. + + **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer. + + + This is likely due to an outdated version of the CLI. + + **Solution:** Run `mint update` to get the latest changes. + + + If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine. + + If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation. + + If you have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`. + + 1. Uninstall the old package: + ```bash + npm uninstall -g mintlify + ``` + 2. Clear your npm cache: + ```bash + npm cache clean --force + ``` + 3. Reinstall the new package: + ```bash + npm i -g mint + ``` + + \ No newline at end of file diff --git a/v2/quickstart.mdx b/v2/quickstart.mdx new file mode 100644 index 000000000..76200d99c --- /dev/null +++ b/v2/quickstart.mdx @@ -0,0 +1,251 @@ +--- +title: "Quickstart" +description: "Deploy your documentation in minutes" +icon: "rocket" +--- + +This quickstart guide shows you how to set up and deploy your documentation site in minutes. + +After completing this guide, you will have a live documentation site ready to customize and expand. + + + +**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding. + + + +## Getting started + +After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format: + +``` +https://.mintlify.app +``` + +Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/). + + + Mintlify Domain + Mintlify Domain + + +Your site's URL is available immediately. Use this URL for testing and sharing with your team while you are setting up your docs site. + +### Install the GitHub App + +Mintlify provides a GitHub App that automates deployment when you push changes to your repository. + +Install the GitHub App by following the instructions from the onboarding checklist or your dashboard. + +1. Navigate to **Settings** in your Mintlify dashboard. +2. Select **GitHub App** from the sidebar. +3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page. +4. Select the organization or user account where you want to install the app. +5. Select the repositories that you want to connect. + + + GitHub App Installation + GitHub App Installation + + + + Update the GitHub App permissions if you move your documentation to a different repository. + + +### Authorize your GitHub account + +1. Navigate to **Settings** in your Mintlify dashboard. +2. Select **My Profile** from the sidebar. +3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page. + + + An admin for your GitHub organization may need to authorize your account depending on your organization settings. + + +## Editing workflows + +Mintlify offers two workflows for creating and maintaining your documentation: + + + For users who prefer working with existing tools in their local environment. Click to jump to this section. + + + + For users who prefer a visual interface in their web browser. Click to jump to this section. + + +## Code-based workflow + +The code-based workflow integrates with your existing development environment and Git repositories. This workflow is best for technical teams who want to manage documentation alongside code. + +### Install the CLI + +To work locally with your documentation, install the Command Line Interface (CLI), called [mint](https://www.npmjs.com/package/mint), by running this command in your terminal: + + + ```bash npm + npm i -g mint + ``` + + ```bash pnpm + pnpm add -g mint + ``` + + + + You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide. + + +### Edit the documentation + +After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page: + +1. Open your repository created during onboarding. +2. Open `index.mdx` and locate the top of the file: + +```mdx index.mdx +--- +title: "Introduction" +description: "This is the introduction to the documentation" +--- +``` + +3. Update the `title` field to `"Hello World"`. + +```mdx index.mdx {2} +--- +title: "Hello World" +description: "This is the introduction to the documentation" +--- +``` + +### Preview the changes + +To preview the changes locally, run the following command: + +```bash +mint dev +``` + +Your preview will be available at `localhost:3000`. + + + Mintlify Dev + Mintlify Dev + + +### Push the changes + +When you are ready to publish your changes, push them to your repository. + +Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com). + +After the deployment completes, your latest update will be available at `.mintlify.app`. + + + Optionally, skip the web editor workflow and jump to adding a custom domain. + + +## Web editor workflow + +The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. This workflow is best for people who want to work in their web browser without additional local development tools. + +### Access the web editor + +1. Log in to your [dashboard](https://dashboard.mintlify.com). +2. Select **Editor** on the left sidebar. + + + If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor. + + + + The Mintlify web editor in the visual editor mode + The Mintlify web editor in the visual editor mode + + +### Edit the documentation + +In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page: + +Find and select `index.mdx` in the file explorer. + +Then, in the editor, update the title field to "Hello World". + + + Editing in Web Editor + Editing in Web Editor + + + + The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools. + + +### Publish your changes + +When you're satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. + + + Use branches to preview and review changes through pull requests before deploying to your live site. + + +For more details about using the web editor, including using branches and pull requests to collaborate and preview changes, see our [web editor documentation](/v2/editor/getting-started). + +## Adding a custom domain + +While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation. + +To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard. + + + Custom Domain + Custom Domain + + +Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider. + + +| Record Type | Name | Value | TTL | +|-------------|------|-------|-----| +| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 | +
+ + + DNS changes can take up to 48 hours to propagate, though changes often complete much sooner. + + +## Next steps + +Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation: + + + Configure site-wide styling, navigation, integrations, and more with the `docs.json` file. + + + Learn how to customize colors, fonts, and the overall appearance of your documentation site. + + + Structure your documentation with intuitive navigation to help users find what they need. + + + Enhance your documentation with interactive components like accordions, tabs, and code samples. + + + Create interactive API references with OpenAPI and AsyncAPI specifications. + + +## Troubleshooting + +If you encounter issues during the setup process, check these common troubleshooting solutions: + + + + Make sure you have Node.js v19+ installed and that you run the `mint dev` command from the directory containing your `docs.json` file. + + + Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors. + + + Verify that your DNS records are set up correctly and allow sufficient time for DNS propagation (up to 48 hours). You can use tools like [DNSChecker](https://dnschecker.org) to verify your CNAME record. + + \ No newline at end of file