From 5afd8d1b6f51979ee5da484e7b666354da89e395 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 17 Mar 2025 18:10:18 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- advanced/dashboard/permissions.mdx | 8 +- advanced/dashboard/sso.mdx | 27 +++--- advanced/mcp/generate.mdx | 39 +++++---- advanced/rest-api/overview.mdx | 17 ++-- docs.json | 22 +++-- quickstart.mdx | 131 ++++++++++++----------------- 6 files changed, 116 insertions(+), 128 deletions(-) diff --git a/advanced/dashboard/permissions.mdx b/advanced/dashboard/permissions.mdx index d39d099a4..0c5b37cd6 100644 --- a/advanced/dashboard/permissions.mdx +++ b/advanced/dashboard/permissions.mdx @@ -3,14 +3,14 @@ title: 'Editor Permissions' description: 'Allow more members of your team to update your docs' --- -The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify. +The team member who created your initial docs will have update access to your documentation, as long as they push to your documentation repository with the same GitHub account that was used while signing up for Mintlify. -If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check. +If another editor attempts to update the docs while on the free plan, you will see a warning in your Git commit check. -In the details of the git check warning, you'll find the link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates. +In the details of the Git check warning, you'll find a link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates. -Learn more about our pricing [here](https://mintlify.com/pricing). +Learn more about our pricing [here](https://mintlify.com/pricing). \ No newline at end of file diff --git a/advanced/dashboard/sso.mdx b/advanced/dashboard/sso.mdx index 4a70acc7a..ab0a24882 100644 --- a/advanced/dashboard/sso.mdx +++ b/advanced/dashboard/sso.mdx @@ -3,7 +3,7 @@ title: "Single Sign-On (SSO)" description: "Customize how your team can login to your admin dashboard" --- -Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us! +Use Single Sign-On (SSO) to access your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO. If you use another provider, please contact us! SSO functionality is available on our Enterprise plan. [Contact @@ -20,17 +20,17 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl Enter the following: - * Single sign-on URL (provided by Mintlify) + * Single Sign-On URL (provided by Mintlify) * Audience URI (provided by Mintlify) * Name ID Format: `EmailAddress` * Attribute Statements: - | Name | Name format | Value + | Name | Name Format | Value | ---- | ----------- | ----- | `firstName` | Basic | `user.firstName` | | `lastName` | Basic | `user.lastName` | - Once the application is set up, navigate to the sign-on tab and send us the metadata URL. + Once the application is set up, navigate to the Sign-On tab and send us the metadata URL. We'll enable the connection from our side using this information. @@ -38,15 +38,15 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Under `Applications`, click to create a new app integration using OIDC. + Under `Applications`, click to create a new app integration using OpenID Connect (OIDC). You should choose the `Web Application` application type. - Select the authorization code grant type and enter the Redirect URI provided by Mintlify. + Select the Authorization Code grant type and enter the Redirect URI provided by Mintlify. - Once the application is set up, navigate to the General tab and locate the client ID & client secret. - Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. + Once the application is set up, navigate to the General tab and locate the Client ID & Client Secret. + Please securely provide us with these, along with your Okta instance URL (e.g., `.okta.com`). You can send these via a service like 1Password or SendSafely. @@ -64,23 +64,23 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. + Copy the provided SSO URL, Entity ID, and X.509 certificate and send it to the Mintlify team. ![](/images/gsuite-saml-metadata.png) - On the Service provider details page, enter the following: + On the Service Provider details page, enter the following: * ACS URL (provided by Mintlify) * Entity ID (provided by Mintlify) - * Name ID format: `EMAIL` + * Name ID Format: `EMAIL` * Name ID: `Basic Information > Primary email` ![](/images/gsuite-sp-details.png) - On the next page, enter the following attribute statements: + On the next page, enter the following Attribute Statements: | Google Directory Attribute | App Attribute | | -------------------------- | ------------- | | `First name` | `firstName` | @@ -90,5 +90,4 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - - + \ No newline at end of file diff --git a/advanced/mcp/generate.mdx b/advanced/mcp/generate.mdx index d513a7d86..a465a5d8a 100644 --- a/advanced/mcp/generate.mdx +++ b/advanced/mcp/generate.mdx @@ -9,30 +9,37 @@ description: "Learn how to set up your own MCP Server" [Installing and using the Mintlify MCP Server](/advanced/mcp/quickstart) page. -## Get started +## Get Started -Run `npm i mcp` to install the `mcp` CLI. +Run `npm i mcp` to install the MCP CLI. -In the [dashboard](https://dashboard.mintlify.com/products/mcp) go to `MCP Server`, on this page toggle to see your unique installation command. This is the command to install your MCP Server with the `mcp` CLI. +In the [dashboard](https://dashboard.mintlify.com/products/mcp), navigate to the `MCP Server` section. On this page, toggle the view to see your unique installation command. This command will install your MCP Server using the MCP CLI. - Make sure to toggle OpenAPI access to allow the MCP server to access **all** - endpoints in your OpenAPI spec. + Make sure to toggle OpenAPI access to allow the MCP Server to access **all** + endpoints in your OpenAPI specification. -## Start the MCP server locally +## Start the MCP Server Locally - - Run the following command to install the server: ```bash npx mcp add [your - subdomain] ``` + + Run the following command to install the server: + ```bash + npx mcp add [your subdomain] + ``` - - If your API requires an authentication token, tell your end-customer to get - it and apply it when given this response: ``` > What is the Authorization - (basic token)? ``` Otherwise, you can skip this step. + + If your API requires an authentication token, instruct your end-customer to provide it when prompted with this response: + ``` + > What is the Authorization (basic token)? + ``` + If authentication is not required, you can skip this step. - - You can now run: ```bash npm --prefix ~/.mcp/[your subdomain] start ``` + + You can now run: + ```bash + npm --prefix ~/.mcp/[your subdomain] start + ``` - + \ No newline at end of file diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index c1f399434..d3152ad18 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -7,8 +7,7 @@ title: Overview You can leverage the REST API to programmatically trigger an update when desired. - While the primary use-case will be to trigger updates, we will be adding more and more - functionality to the API overtime. Let us know what else you want to see in + While the primary use case will be to trigger updates, we will be adding more functionality to the API over time. Let us know what else you would like to see in [our community](https://mintlify.com/community)! @@ -16,27 +15,27 @@ You can leverage the REST API to programmatically trigger an update when desired You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is -associated with the entire org and can be used across multiple deployments. +associated with the entire organization and can be used across multiple deployments. -## Admin API key +## Admin API Key The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/advanced/rest-api/update/trigger). -## Chat API key +## Chat API Key -The Chat API allows you to embed the AI chat experience grounded in your docs and continually kept up to date into any application of your choosing. +The Chat API allows you to embed an AI chat experience into any application of your choosing. This chat experience is grounded in your documentation and continuously kept up to date. -Responses include citations so you can point your users to the right places they need to get help. +Responses include citations, allowing you to point your users to the specific documentation pages they need for help. The Chat API token is a public token that can be referenced in your - frontend code whereas the API key is a server-side token that should be kept + frontend code, whereas the API key is a server-side token that should be kept secret. Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use -the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). +the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). \ No newline at end of file diff --git a/docs.json b/docs.json index edd11836e..fe4a3eae8 100644 --- a/docs.json +++ b/docs.json @@ -22,7 +22,10 @@ { "group": "Editing", "icon": "pen-paintbrush", - "pages": ["development", "web-editor"] + "pages": [ + "development", + "web-editor" + ] }, "settings/global", { @@ -37,7 +40,8 @@ ] }, "themes", - "migration" + "migration", + "quickstart" ] }, { @@ -135,7 +139,9 @@ "icon": "house-lock", "pages": [ "advanced/dashboard/sso", - "advanced/dashboard/permissions" + "advanced/dashboard/permissions", + "advanced/dashboard/permissions", + "advanced/dashboard/sso" ] }, { @@ -143,6 +149,7 @@ "icon": "server", "pages": [ "advanced/mcp/quickstart", + "advanced/mcp/generate", "advanced/mcp/generate" ] }, @@ -164,7 +171,8 @@ "advanced/rest-api/chat/create-topic", "advanced/rest-api/chat/generate-message" ] - } + }, + "advanced/rest-api/overview" ] } ] @@ -262,7 +270,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -374,4 +384,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index bc95e6932..96dffa943 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -17,74 +17,63 @@ icon: "rocket" ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +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. +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. Get started by onboarding through the [dashboard](https://dashboard.mintlify.com) or cloning our [starter kit](https://github.com/mintlify/starter). - - - 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. + + Install our GitHub App to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - - - If you want your docs to live alongside your code as a monorepo setup, you - can: 1. Move your docs content to your monorepo. 2. Specify the path to your - `docs.json` in the - [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) - - Monorepo setup - Monorepo setup - - + + If you want your docs to live alongside your code in a monorepo setup, you can: + 1. Move your docs content to your monorepo + 2. Specify the path to your `docs.json` in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) + + + Monorepo setup + Monorepo setup + + ### Updating the Content -Mintlify enables you to easily customize the style, structure, and content of -your docs. +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`. + + 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). - + + Learn more about how to use the web editor in our [guide](/web-editor). - - - Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations: + + Easily customize colors, logos, and buttons among other configurations in your `docs.json` file. Start with these basic configurations: ```json "name": "Your Company" @@ -101,13 +90,11 @@ your docs. }, ``` - A full list of supported configurations can be found at [global settings](/settings/global). - + A full list of supported configurations can be found in our [global settings](/settings/global). - - - Add content with simple MDX files. Initiate your pages with this template: + + Add content with simple MDX files. Initialize your pages with this template: ```md --- @@ -118,69 +105,55 @@ your docs. ``` 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) - + + Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub App is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). + + ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) + - - + You can easily set up your API references using an OpenAPI document. - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL. + 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL: ```json "openapi": "link-to-your-openapi-file" ``` - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: + 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files: ```bash npx @mintlify/scraping@latest openapi-file ``` - 3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`. + 3. Include the generated endpoint MDX files in your `docs.json` under `navigation` For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). - - - - Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). + + Our in-house analytics give you insights into page views, search analytics, session recordings, and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). - - We provide a white-glove migration service as part of our Enterprise plan. - Interested? You can request it by [contacting us](mailto:sales@mintlify.com). + We 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://dashboard.mintlify.com/settings) to add a custom domain. + + Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan. -![Custom Domain](/images/custom-domain.png) + Navigate to your [dashboard settings](https://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). +Congratulations! You've set up your Mintlify docs, and they're looking amazing! Need support or want to give feedback? Join our [community](https://mintlify.com/community) or email us at [support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file