diff --git a/advanced/dashboard/permissions.mdx b/advanced/dashboard/permissions.mdx index d39d099a..3d12af4c 100644 --- a/advanced/dashboard/permissions.mdx +++ b/advanced/dashboard/permissions.mdx @@ -5,12 +5,12 @@ 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. -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 GitHub commit check. - - + + Editor gate warning message -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 GitHub commit 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. -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 4a70acc7..eaee539d 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 to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO. For other providers, please contact us! SSO functionality is available on our Enterprise plan. [Contact @@ -20,12 +20,12 @@ 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` | @@ -45,8 +45,8 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl 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. @@ -58,19 +58,21 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. + Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. + ![](/images/gsuite-add-custom-saml-app.png) - + - 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) + ![](/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` @@ -83,12 +85,11 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl On the next page, enter the following attribute statements: | Google Directory Attribute | App Attribute | | -------------------------- | ------------- | - | `First name` | `firstName` | + | `First name` | `firstName` | | `Last name` | `lastName` | Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account! - - + \ No newline at end of file diff --git a/advanced/mcp/generate.mdx b/advanced/mcp/generate.mdx index d513a7d8..37e8196f 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 display 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: + ```bash + > What is the Authorization (basic token)? + ``` + Otherwise, 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/mcp/quickstart.mdx b/advanced/mcp/quickstart.mdx index 45516030..70356acb 100644 --- a/advanced/mcp/quickstart.mdx +++ b/advanced/mcp/quickstart.mdx @@ -5,7 +5,7 @@ description: "[MCP](https://modelcontextprotocol.io/introduction) simplifies how ## Introduction -The MCP Generator is a CLI tool that generates an MCP server based on your company's documentation & OpenAPI specification if available. It takes in your documentation and a OpenAPI spec and outputs an MCP server that can be used with any MCP client. The MCP Generator is delivered via [npm package](https://www.npmjs.com/package/mcp) and generates an MCP server that can be used with any MCP client. +The MCP Generator is a CLI tool that generates an MCP server based on your company's documentation and OpenAPI specification (if available). It takes in your documentation and OpenAPI spec and outputs an MCP server that can be used with any MCP client. The MCP Generator is delivered via [npm package](https://www.npmjs.com/package/mcp) and generates an MCP server that can be used with any MCP client. Mintlify enables you to create an MCP server that allows AI tools to interact with your docs in these key scenarios: @@ -16,42 +16,45 @@ Mintlify enables you to create an MCP server that allows AI tools to interact wi **all** endpoints in your OpenAPI spec. -## Install the MCP server +## Install the MCP Server This page is dedicated to the Mintlify MCP Server. If you are looking for information on generating your MCP, please refer to the [MCP Generator](/advanced/mcp/generate) page. -## Example installation with the Mintlify MCP server +## Example Installation with the Mintlify MCP Server -To use the Mintlify MCP server you will need an [API key](https://mintlify.com/docs/advanced/rest-api/overview#authentication) from your Mintlify account. If you don't have one, navigate to `Settings > API Keys > Chat API Key` and create a new key. +To use the Mintlify MCP server, you will need an [API key](https://mintlify.com/docs/advanced/rest-api/overview#authentication) from your Mintlify account. If you don't have one, navigate to `Settings > API Keys > Chat API Key` and create a new key. -## Start the MCP server locally +## Start the MCP Server Locally Run the following command to install the server: + ```bash npx mcp add mintlify ``` The following response will be given after running the previous command: + ``` > What is the Authorization (basic token)? ``` + Using your API chat key, copy the authentication token and paste it into the CLI. - You can now run: + ```bash npm --prefix ~/.mcp/mintlify start ``` -## Use your server with Claude +## Use Your Server with Claude Download the [Claude Desktop App](https://claude.ai/download) @@ -60,9 +63,10 @@ To use the Mintlify MCP server you will need an [API key](https://mintlify.com/d Once you have the Claude Desktop App installed, follow these steps: - + Add the following to the `claude_desktop_config.json`: + ```json { "mcpServers": { @@ -80,9 +84,9 @@ Once you have the Claude Desktop App installed, follow these steps: If you click on it, you should see the available MCP Tools in your server. + Claude MCP - - + \ No newline at end of file diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index c1f39943..499a73f7 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -7,36 +7,29 @@ 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 - [our community](https://mintlify.com/community)! + 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)! ## Authentication -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. +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 organization and can be used across multiple deployments. - - + + API key generation interface -## 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, grounded in your documentation and continually kept up to date, into any application of your choosing. Responses include citations so you can point your users to the right places they need to get 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 - secret. + The Chat API token is a public token that can be referenced in your frontend code, whereas the Admin 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). +Now that you have an API key, check out our [example repository](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). \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 9ef4eb10..824be17d 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -3,11 +3,11 @@ title: 'MDX Setup' description: 'Generate docs pages for your API endpoints using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API Playground, request examples, and response examples. - In your `docs.json` file, define your base URL and auth method: + In your `docs.json` file, define your base URL and authentication method: ```json "api": { @@ -15,13 +15,13 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js "server": "https://mintlify.com/api", // string array for multiple base URLs "auth": { "method": "key", - "name": "x-api-key" // options: bearer, basic, key. + "name": "x-api-key" // options: bearer, basic, key } } } ``` - If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field: + If you do not want to show an API Playground, you don't need to include authentication types. Hide the playground with the following field: ```json "api": { @@ -35,7 +35,6 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: ```md @@ -52,23 +51,21 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js ``` - - If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - + If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file: + You can also override the globally-defined display mode for the API Playground per page by adding `playground` at the top of the MDX file: ```md --- title: 'Create new user' api: 'POST https://api.mintlify.com/user' playground: 'none' + --- ``` - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](/settings/navigation). - + \ No newline at end of file diff --git a/content/components/code.mdx b/content/components/code.mdx index 8b3334e2..6dbb187e 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -32,7 +32,7 @@ helloWorld(); Put the name of your programming language after the three backticks to get syntax highlighting. -We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported. +We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. The [Test Drive Prism](https://prismjs.com/test.html#language=markup) page lists all supported languages. ```java class HelloWorld { @@ -54,7 +54,7 @@ class HelloWorld { ## Names -Add a title after the programming language to set the name of your code example. The text can be anything as long as its all in one line. +Add a title after the programming language to set the name of your code example. The text can be anything as long as it's all on one line. ```javascript Code Block Example const hello = "world"; @@ -90,7 +90,7 @@ sayHello(); ## Expandable -If you have a long code block and `[expandable]` after your title to make it close and expand. +Add `[expandable]` after your title to make a long code block collapsible. ```python library.py [expandable] from datetime import datetime, timedelta @@ -194,7 +194,7 @@ sayHello(); ## Code Groups -Want to display multiple code examples in one code box? Check out the Code Group docs: +Want to display multiple code examples in one code box? Check out the Code Group documentation: Read the reference for the Code Group component - + \ No newline at end of file diff --git a/docs.json b/docs.json index edd11836..6be137e6 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", { @@ -69,7 +72,8 @@ "icon": "markdown", "pages": [ "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "api-playground/mdx/authentication", + "api-playground/mdx/configuration" ] }, "api-playground/troubleshooting" @@ -127,7 +131,8 @@ "settings/authentication-personalization/personalization-setup/oauth" ] }, - "settings/authentication-personalization/sending-data" + "settings/authentication-personalization/sending-data", + "settings/authentication-personalization/authentication" ] }, { @@ -135,7 +140,9 @@ "icon": "house-lock", "pages": [ "advanced/dashboard/sso", - "advanced/dashboard/permissions" + "advanced/dashboard/permissions", + "advanced/dashboard/permissions", + "advanced/dashboard/sso" ] }, { @@ -143,7 +150,9 @@ "icon": "server", "pages": [ "advanced/mcp/quickstart", - "advanced/mcp/generate" + "advanced/mcp/generate", + "advanced/mcp/generate", + "advanced/mcp/quickstart" ] }, { @@ -164,7 +173,8 @@ "advanced/rest-api/chat/create-topic", "advanced/rest-api/chat/generate-message" ] - } + }, + "advanced/rest-api/overview" ] } ] @@ -192,7 +202,8 @@ "content/components/steps", "content/components/tabs", "content/components/tooltips", - "content/components/update" + "content/components/update", + "content/components/code" ] }, { @@ -262,7 +273,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -374,4 +387,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 81c5b8a7..a140e4b5 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -14,12 +14,12 @@ documentation content by requiring users to authenticate before viewing any cont You can authenticate users through handshake methods such as: - [Password](./authentication-setup/password) -- [JWT](./authentication-setup/jwt) -- [OAuth](./authentication-setup/oauth) -- [Mintlify dashboard](./authentication-setup/mintlify) +- [JWT (JSON Web Token)](./authentication-setup/jwt) +- [OAuth 2.0](./authentication-setup/oauth) +- [Mintlify Dashboard](./authentication-setup/mintlify) -Authentication is similar to our [Personalization](./personalization) offering, but with guaranteed privacy. In addition +Authentication is similar to our [Personalization](./personalization) offering but with guaranteed privacy. In addition to securing your documentation content, all features that are available via Personalization are also available via Authentication. -Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization). +Check out our docs for more information on [choosing Authentication vs Personalization](./authentication-vs-personalization). \ No newline at end of file