diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index f9d74b067..927cc4535 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -4,16 +4,15 @@ title: Overview ## Trigger Updates -Leverage the REST API to programmatically trigger an update when desired. -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 +You can use our REST API to automatically start updates whenever you need them. +The main purpose is to let you control when updates happen. We're working on adding more +features to the API over time. Have suggestions? Share them with us in [our community](https://mintlify.com/community)! ## Authentication -You can generate an API key through -[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is -associated with the entire org and can be used across multiple deployments. +To use the API, you'll need an API key. You can create one through +[the dashboard](https://dashboard.mintlify.com/settings/integrations). This key works for your whole organization and can be used across all your deployments. @@ -21,12 +20,13 @@ associated with the entire org and can be used across multiple deployments. ## Discovery API -The Discovery API allows you to embed an AI chat experience grounded in your docs 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 Discovery API helps you add AI-powered chat to your documentation. This chat feature understands your docs and stays current with any changes you make. +When the AI responds, it includes references to show users exactly where the information came from. ## Getting Started -To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget): +Follow these steps to begin: +1. First, create a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget): - The Discovery 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. + There are two types of keys: + - The Discovery API token is public and can be used in your website's code + - The API key is private and should be kept secure on your server -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). +Once you have your API key, you can see how to use it by checking out our [example code](https://github.com/mintlify/discovery-api-example). Want to see it in action? Visit [chat.mintlify.com](https://chat.mintlify.com) to try a live demo. \ No newline at end of file diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 13ff2d841..7827defcf 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -5,9 +5,7 @@ description: "Host documentation at a /docs subpath using Cloudflare Workers" ## Create Cloudflare Worker -Navigate to the `Workers & Pages > Create application > Create worker`. You -should be able to presented with the following screen where you can create a new -Cloudlfare worker. +To get started, go to `Workers & Pages > Create application > Create worker` in your Cloudflare dashboard. You'll see a screen where you can set up a new Cloudflare worker. Create a Cloudflare worker @@ -15,10 +13,12 @@ Cloudlfare worker. ### Add custom domain -Once the worker is created, click `Configure worker`. Navigate to the worker -`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain -into the list - we recommend you add both the version with and without `www.` -prepended to the domain. +After creating your worker, follow these steps: +1. Click `Configure worker` +2. Go to `Settings > Triggers` +3. Click `Add Custom Domain` +4. Add your domain to the list + - We suggest adding two versions: one with `www.` and one without it -If you have trouble setting up a custom subdirectory, -[contact our support team](mailto:sales@mintlify.com) and we'll walk you through -upgrading your hosting with us. +Need help setting up your custom subdirectory? [Contact our support team](mailto:sales@mintlify.com) and we'll help you upgrade your hosting. ### Edit Worker Script -Click on `Edit Code` and add the following script into the worker's code. +Now you'll need to add some code to your worker. Click on `Edit Code` and copy the script below into the code editor. Cloudflare edit code - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. + Before using the code, you need to make two changes in `DOCS_URL`: + 1. Replace `[SUBDOMAIN]` with your unique subdomain + 2. Replace `CUSTOM_URL` with your website's base URL ```javascript @@ -76,5 +75,4 @@ async function handleRequest(request) { } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +Click `Deploy` to save your changes. Please note that it might take a few hours before all changes are fully active across the network. \ No newline at end of file diff --git a/api-playground/openapi/advanced-features.mdx b/api-playground/openapi/advanced-features.mdx index a262422b4..b55a50498 100644 --- a/api-playground/openapi/advanced-features.mdx +++ b/api-playground/openapi/advanced-features.mdx @@ -1,25 +1,25 @@ --- title: "Advanced Features" -description: "Support for advanced OpenAPI features" +description: "Learn how to use powerful OpenAPI features" --- -OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them with Mintlify. +OpenAPI 3 offers several advanced ways to describe complex APIs. Let's explore how to use these features with Mintlify. ## `oneOf`, `anyOf`, `allOf` -For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the [Swagger documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially: +OpenAPI provides three special keywords to help you work with complex data types: `oneOf`, `anyOf`, and `allOf`. These keywords let you combine different data structures. Here's what each one does: -- `oneOf` functions like an "exclusive-or" operator -- `anyOf` functions like an "or" operator -- `allOf` functions like an "and" operator +- `oneOf`: Means "pick exactly one option from the list" +- `anyOf`: Means "pick one or more options from the list" +- `allOf`: Means "include everything from all options" -Mintlify treats the `oneOf` and `anyOf` keywords the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user. +In Mintlify, we handle `oneOf` and `anyOf` the same way. We've found that most developers use these terms interchangeably, and the difference rarely matters to users. -Mintlify currently does not support the `not` keyword. +Note: Mintlify doesn't support the `not` keyword at this time. -### Combining schemas with `allOf` +### Using `allOf` to Combine Data Structures -Mintlify performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging [OpenAPI's reusable `components`](https://swagger.io/docs/specification/components/). +Mintlify makes it easy to read combined data structures. For example, when you join two objects with `allOf`, we show all their properties together in one place. This is especially helpful when you're using [reusable components in OpenAPI](https://swagger.io/docs/specification/components/). ```yaml org_with_users: @@ -52,9 +52,9 @@ components: -### Providing options with `oneOf` and `anyOf` +### Offering Choices with `oneOf` and `anyOf` -When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. For example, here's how you might display two different types of delivery addresses: +When you use `oneOf` or `anyOf`, Mintlify shows the options in tabs. To make these tabs easy to understand, give each option a clear title. Here's an example showing two different ways to write a delivery address: ```yaml delivery_address: @@ -94,21 +94,21 @@ delivery_address: ## `x-codeSamples` -If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within any request method, and has the following schema: +If your users work with your API through an SDK instead of direct API calls, you can add example code to your documentation. Use the `x-codeSamples` feature to add these examples. You can add this to any API endpoint, and it needs: - The language of the code sample. + The programming language used in the example - The label for the sample. This is useful when providing multiple examples for a single endpoint. + A name for the example (helpful when you have multiple examples) - The source code of the sample. + The actual code for the example -Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. +Here's an example from a plant tracking app that has both a command-line tool and a JavaScript SDK: ```yaml paths: @@ -134,4 +134,4 @@ paths: source: | const planter = require('planter'); planter.list({ potted: true }); -``` +``` \ No newline at end of file diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bc24fbbf6..d44c6a11e 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -1,20 +1,21 @@ --- title: "OpenAPI Setup" -description: "Reference OpenAPI endpoints in your docs pages" +description: "Learn how to add API documentation to your pages" --- -## Add an OpenAPI specification file +## Add an OpenAPI File -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+. +To document your API endpoints, you'll need a valid OpenAPI file in either JSON or YAML format. This file needs to follow the [OpenAPI 3.0+ specification](https://swagger.io/specification/). -## Auto-populate API pages +## Quick Setup: Auto-generate API Pages -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. +The easiest way to get started is to add an `openapi` field to your `mint.json` file. You can either: +- Point to an OpenAPI file in your docs folder +- Link to an OpenAPI file hosted online -**Example with Anchors:** +Mintlify will then create pages for each API endpoint automatically. + +**Setting up with Anchors:** ```json {5} { @@ -31,7 +32,7 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta ![](/images/anchors-autogeneration-anchors.png) -**Example with Tabs:** +**Setting up with Tabs:** ```json {6} { @@ -47,66 +48,54 @@ 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. +Check if your OpenAPI file is valid with this command:
`mintlify openapi-check ` -* `description`: The `description` field from the OpenAPI operation, if present. +When you use this auto-generate option, your pages will have these default settings: +* The page title will use the OpenAPI operation's `summary` field, or create one from the endpoint details +* The description will come from the OpenAPI operation's `description` field +* The version will match what's in your anchor or tab settings -* `version`: The `version` value from the anchor or tab, if present. +Need more control? You can create custom pages for each API endpoint using MDX files. -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. +## Custom API Pages with MDX -## Create MDX files for API pages +Sometimes you might want to: +- Change how the page information appears +- Add extra content +- Skip certain API endpoints +- Change the order of 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). +In these cases, you'll need to create MDX files for your API endpoints. Here's [an example from Elevenlabs](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2). ![](/images/elevenlabs-mdx-autogeneration-example.png) -### Autogenerate files +### Create MDX Files Automatically -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. +If you have many API endpoints, creating MDX files by hand can take a long time. Our Mintlify [scraper tool](https://www.npmjs.com/package/@mintlify/scraping) can create these files for you: ```bash 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. +Want to save the files in a specific folder? Use the `-o` option: ```bash 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. + Your OpenAPI file must be valid for this to work. -### Manually specify files +### Create MDX Files by Hand -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. +You can also create MDX pages manually. Just add an `openapi` field in the page's settings to link it to your API endpoint. -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. +This will automatically add the endpoint's details and an interactive API playground to your page. -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. +If you have multiple OpenAPI files, include the file path to help Mintlify find the right one: ```md Example @@ -118,7 +107,7 @@ only one OpenAPI file - it will automatically detect your OpenAPI file. ```md Format --- - title: "title of the page" + title: "page title" openapi: openapi-file-path method path --- ``` @@ -127,15 +116,12 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.
- 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. + Make sure the method and path match exactly what's in your OpenAPI file. -## Create MDX files for OpenAPI schemas +## Pages for API Data Types -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: +You can also create pages that explain the data types (schemas) defined in your OpenAPI file: ```md Example @@ -146,7 +132,7 @@ defined in an OpenAPI document's `components.schemas` field: ```md Format --- - openapi-schema: "schema-key" + openapi-schema: "schema-name" --- ``` \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 57cd93680..a9a513496 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -1,32 +1,37 @@ --- title: "Writing OpenAPI" -description: "Use OpenAPI features to enhance your Mintlify docs" +description: "Learn how to use OpenAPI features to make your Mintlify docs better" --- -## Describing your API +## Getting Started with OpenAPI -There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites: -- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) for familiarizing yourself with the OpenAPI syntax -- [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for all the details about the newest OpenAPI specification -- [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) for debugging your OpenAPI document -- [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action +Want to learn how to write OpenAPI documents? Here are the best tools to help you get started: +- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) - Learn the basics of OpenAPI +- [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) - Full details about the latest version +- [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) - Check your OpenAPI document for errors +- [Swagger's Editor](https://editor.swagger.io/) - See working examples in action - Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). + Most of Swagger's OpenAPI Guide covers version 3.0, but it works for v3.1 too. Want to know what changed between versions? Check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). -## Specifying the URL for your API +## Setting Up Your API's Web Address -In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). +Every API has a base web address (URL) where it lives. In OpenAPI, you set this using the `servers` field. You'll need this for features like the API Playground to work. Learn how to set up your server URL by reading the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). -The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request. +When you use the API Playground, it will use these server URLs to send requests. If you list multiple servers, you'll see a dropdown menu to switch between them. Without a server URL, the API Playground will only work in simple mode and won't send real requests. -If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation. +Does your API use different web addresses for different features? No problem! You can [set different server URLs](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for specific parts of your API. -## Specifying authentication +## Setting Up Security -Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. +Most APIs need users to prove who they are before they can use them. This is called authentication. OpenAPI lets you set this up using the `securitySchemes` field. It supports common security methods like: +- [Basic Authentication](https://swagger.io/docs/specification/authentication/basic-authentication/) (username and password) +- [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) (using tokens) +- [API Keys](https://swagger.io/docs/specification/authentication/api-keys/) -The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. +To use these security methods in your API, you'll need the `security` field. Since this can be tricky to set up, check out [Swagger's guide to authentication](https://swagger.io/docs/specification/authentication/) for help and examples. -If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. +The API Playground will automatically add the right security fields based on your OpenAPI settings. + +Need different security for different parts of your API? You can [set different security requirements](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for specific operations. \ No newline at end of file diff --git a/changelog/overview.mdx b/changelog/overview.mdx index ad2c56f93..b6cf7a884 100644 --- a/changelog/overview.mdx +++ b/changelog/overview.mdx @@ -8,13 +8,10 @@ mode: "center" Authentication screenshot - Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs. - - + Keep your docs private by adding password protection. You can use JWT, OAuth, or a simple password that everyone shares. This helps you create private internal documentation or keep your content away from competitors. - ## AI Assistant @@ -22,11 +19,11 @@ mode: "center" AI Assistant - You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request. + Our new AI tool can help you update your docs. Just tell it what you want to change, and it will suggest updates by creating a pull request. ## GitLab Integration Upgrade - We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started. + We've made it easier to work with GitLab, including automatic updates and preview options. See how to set it up in our [GitLab guide](/settings/gitlab). ## Web Editor @@ -34,9 +31,9 @@ mode: "center" Web Editor - We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown. + Our web editor is now better than ever. You can edit your docs like you would in a regular word processor, and it automatically handles the markdown formatting. - Check out our [docs on getting started with Web Editor](/web-editor). + Learn more in our [Web Editor guide](/web-editor). ## /llms.txt support @@ -44,23 +41,22 @@ mode: "center" llms.txt support - All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org) + Your docs are now automatically available at /llms.txt and /llms-full.txt, making it easier for AI tools to read your documentation. Learn more about this new feature at [llms.txt standard](https://llmstxt.org). - ## Localization + ## Multiple Languages - You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale. + You can now create your docs in different languages, similar to how versions work. When you add a language option, built-in text like "Was this page helpful?" will also show up in that language. - ### Quality Improvements + ### Other Improvements - * Return chat & search results based on the current version that the user is reading - - * Authenticate users with OAuth, in addition to JWT or Shared Session tokens. + * Search results now match the version you're currently reading + * Added OAuth login option, along with JWT and Shared Session tokens ## Changelogs - Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users. + We've created a new tool called the [Update component](/content/components/update) to help you share updates with your users, just like this page. Changelog @@ -68,7 +64,7 @@ mode: "center" ## Code Line Highlighting - You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. + Want to draw attention to specific lines of code? You can now highlight them by adding numbers in curly braces after the language name. ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; @@ -88,9 +84,9 @@ mode: "center" ``` ```` - ## Light mode code blocks + ## Light Mode Code Blocks - Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`: + Code blocks now come with a light mode option. Add this to your `mint.json` to enable it: ```json "codeBlock": { @@ -98,61 +94,43 @@ mode: "center" } ``` - ## Advanced Footer + ## Better Footer Options Advanced Footer - You can now add more links to the standard footer. This upgrade - provides more consistency between landing pages and docs, or greater customization - if you want to spotlight specific pages like socials or status logs. - - ## Filter search based on the current user - - When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content. - - ## Custom Prompts for AI Chat - - You can now customize the prompts for the AI chat. Please reach out to [support](mailto:sales@mintlify.com) if you'd like to customize the prompts. - - ## Dashboard Improvements - - * Added ability to change custom domain to be /docs directly through dashboard settings. - - * Consolidated the login and signup pages to decrease friction and confusion. - - * Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them. - - * Added login with Google OAuth - - * Added ability to add new deployment through dashboard settings. - - ## Bug Fixes - - * Can now use leading slashes in navigation. - - * Can now edit CSS & JS files in the web editor. + You can now add more links to your footer. This helps match your docs pages with your main website, and lets you highlight important pages like social media or status updates. - * Fixed `suggestEdit` not showing up even when enabled. + ## Personalized Search - * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results. + When you turn on personalization, users will only see search results they're allowed to access. - * Don't allow search engines to crawl user-auth protected pages. + ## Custom AI Chat Settings - * Revalidate the cache when an org is deleted. + Want to customize how the AI chat works? Contact our [support team](mailto:sales@mintlify.com) to learn more. - * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages. + ## Dashboard Updates - * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions. + * You can now set up /docs as your custom domain directly in settings + * Combined login and signup into one simpler page + * Added the ability to switch between different organizations + * Added Google login option + * You can now add new deployments through settings - * Add in-line-style support for icons + ## Fixed Issues - * Fixed the pop-in of custom CSS in docs. - - * Properly show in-line code styling in conjunction with links. - - * Maintain scroll position when you click the back button in a browser. + * Navigation now works with leading slashes + * Web editor now handles CSS & JS files + * Fixed the 'suggest edit' button + * Improved keyboard navigation for Search and Chat + * Better protection for private pages from search engines + * Faster cache updates + * Better handling of API documentation + * Improved icon support + * Fixed custom CSS loading + * Fixed how code appears in links + * Better page scrolling when using browser back button @@ -162,185 +140,154 @@ mode: "center" Custom Fonts - Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand. + Make your docs match your brand by using your own fonts or choosing from Google Fonts. - ## Images in Card components + ## Images in Cards - Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](/content/components/cards#image-card). + You can now add images to the top of cards. Learn how in our [card guide](/content/components/cards#image-card). - ## Update Speed Performances + ## Faster Updates Performance Improvements - For large projects (\~3,000 files), the download step for docs updates is now - \~440x faster - a 99.8% time reduction. Across the board, file downloads during - updates are now \~5.5x faster - an 81.8% time reduction. + We've made big improvements to how quickly docs update: + * Large projects now update 440 times faster + * Regular updates are now 5.5 times faster - ## SEO improvements + ## Better Search Results SEO Improvements - We've fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements. - - ## Dashboard Improvements - - * App router migration in the dashboard. - - * Search analytics are now available in the dashboard. - - * Delete an org functionality has been added to the dashboard. - - * Shipped GitLab connection UI. - - * Fix incorrect analytics data. - - * Add-on's can now be directly purchased through the dashboard. + We've improved how our docs look on phones and computers, making them easier to find in search engines. - ## Bug Fixes + ## Dashboard Updates - * Fixed a bug where the top bar would not stretch to the width of the screen when it's in custom mode and the sidebar layout is `sidenav`. + * Updated dashboard design + * Added search statistics + * Added option to delete organizations + * Added GitLab connection screen + * Fixed analytics data issues + * Added direct add-on purchases - * Fix relative positioning of the AI widget. + ## Fixed Issues - ## More - - * **Troubleshooting for API pages**: API pages could be complicated so we listed - common issues to help you sort them out quickly — - [Read the docs](/api-playground/troubleshooting) + * Fixed top bar width issues + * Fixed AI chat positioning + * Added a [troubleshooting guide](/api-playground/troubleshooting) for API pages - ## OpenAPI Reference Pages - - * Endpoints defined by OpenAPI that are complex and recursive are now 98% - smaller. - - * We now show - [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/) - in OpenAPI pages. - - ## File Uploads in API Playground + ## API Documentation Updates - By default, API playground requests are proxied by Mintlify. Now you can use - `disableProxy` to disable this behavior and support request types like file - uploads. + * Simplified complex API documentation + * Added support for additional properties in API pages - * [Learn more about API configurations](/settings/global#api-configurations) + ## File Uploads in API Testing - ## Mobile SEO improvements + You can now upload files when testing APIs by using the `disableProxy` option. + + * [Learn about API settings](/settings/global#api-configurations) - We've fixed the mobile layout of our docs so that they are more SEO-friendly - - including adding proper aria tags to elements. + ## Mobile Improvements - ## Support Form + We've made our docs easier to read on phones and improved how search engines see them. - We added a more detailed support form to the Mintlify dashboard. You can now - submit a form to get in touch with us. + ## Support Help - ## Bug Fixes + We've added a detailed support form in the dashboard to help you reach us more easily. - * Fixed a bug for the Segment integration functionality. + ## Fixed Issues - * We now raise more granular error messages for GitHub permissions when - interacting with the editor. - - * Fixed bugs where the navigation would not properly expand when a direct link - was used. + * Fixed Segment integration + * Better error messages for GitHub permissions + * Fixed navigation expansion with direct links - ## AI Widget + ## AI Chat Widget AI Widget - For `Pro` users, we introduced Mintlify Widget, an extension of your docs to - answer your users' questions when and where they asked. You can add this - AI-powered chatbot to any web page: your landing page, inside your product, or - on your existing documentation pages. - - * [Read the blog announcement](https://mintlify.com/blog/widget) + Pro users can now add our AI chatbot to any webpage. It helps answer user questions wherever they need help. - * [Learn how to install the Widget](/advanced/widget/chat#getting-started) + * [Read about the release](https://mintlify.com/blog/widget) + * [Learn how to add the widget](/advanced/widget/chat#getting-started) ## Pro Plan - We also updated our pricing plans for better customizability and scale. + We've updated our pricing to give you more options. - * [Read the blog announcement](https://mintlify.com/blog/pro-plan) + * [Read about the changes](https://mintlify.com/blog/pro-plan) - ## API Playground Code Example Sync + ## API Examples - When you browse API docs, the selected code example now syncs across your pages. + Your preferred code example now stays selected as you browse API docs. - ## Insights + ## Usage Reports - Currently in beta, this feature summarizes common user questions and patterns - into easy-to-digest reports with AI-powered suggestions on how to improve your - product. + We're testing a new feature that shows you what users are asking about and suggests ways to improve your docs. ## Launch Week Highlights -* Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling. -* Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated searchbar UI. -* Web Editor branching: create branches in our web editor without an IDE. -* User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers. -* OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json. +* New Themes: Choose from pre-made styles like Quill, Prism, or Venus +* Better Search: Find API pages more easily and control what shows up in search +* Web Editor Branches: Create different versions of your docs right in the web editor +* User Personalization: Show custom content to different users +* Easier API Setup: Automatically create API pages from your specifications -## Okta SSO -We now support sign-on via Okta SAML and OIDC. +## Okta Sign-In +You can now sign in using Okta. -## Mintlify REST API -Programmatically rigger updates to your documentation. +## Mintlify API +Update your docs automatically using our programming tools. -## Custom mode -Add a configuration to the metadata to remove all elements except for the top bar. -Example use cases: -* Create a custom global landing page setup with custom components -* Add full-screen videos or image galleries -* Embed custom iFrame demo elements to add intractability to your docs +## Custom Layout Mode +Remove standard page elements to create your own unique pages. Great for: +* Custom landing pages +* Full-screen videos or pictures +* Interactive demos -Check out our [Custom Mode docs](/page#custom-mode). +Learn more in our [Custom Mode guide](/page#custom-mode). - -## Mintlify MDX for VSCode -Call snippets of our pre-built components an dcallouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). +## VSCode Helper +Get quick access to our components without leaving VSCode. [Get it here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). -## Quality Improvements -* Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments -* Versioning with tabs fully supported -* Wildcard redirects now supported -* CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development +## Improvements +* Better dashboard: see update history and manage different projects +* Support for versions with tabs +* New redirect options +* Better error messages when developing locally ## Launch Week Highlights -* Preview Deployments: When you create a pull request, we'll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates. -* Snippets V2: We now support fully reusable components and variables for snippets. -* Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome. -* AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears. +* Preview Links: See how changes look before publishing them +* Better Reusable Content: Create and use content pieces across your docs +* Open-Source Tools: Use our markdown tools in your projects [Help improve them here](https://github.com/mintlify/mdx) +* AI Chat Updates: Track usage and common questions more easily - + \ No newline at end of file diff --git a/content/components/params.mdx b/content/components/params.mdx index e9e1249b9..497b583a2 100644 --- a/content/components/params.mdx +++ b/content/components/params.mdx @@ -1,10 +1,10 @@ --- title: "Parameter Fields" -description: "Set path, query, and body parameters" +description: "Learn how to set path, query, and body parameters" icon: "text-size" --- -`ParamField` components help define the parameters for your APIs or SDKs. Adding a ParamField will automatically add an [API Playground](/api-playground/overview). +The `ParamField` component helps you define parameters for your APIs or SDKs. When you add a ParamField to your documentation, it automatically creates an [API Playground](/api-playground/overview) where users can test the parameters. An example of a parameter field @@ -20,48 +20,52 @@ icon: "text-size" ```jsx Query Example - The filtering command used to sort through the users + The filtering command that helps sort through users ``` ```jsx Body Example - The age of the user. Cannot be less than 0 + The age of the user. Must be 0 or greater ``` -## Props +## Available Properties + +Here are all the properties you can use with ParamField: - Whether it is a query, path, body, or header parameter followed by the name + Choose the parameter type (query, path, body, or header) and add its name - Expected type of the parameter's value + The kind of value you expect for this parameter (like string, number, etc.) - Indicate whether the parameter is required + Sets whether users must provide this parameter or not - Indicate whether the parameter is deprecated + Shows if this parameter is no longer recommended for use - Default value used by the server if the request does not provide a value + The value that will be used if no other value is provided - Value that will be used to initialize the playground + The starting value that will appear in the playground - Placeholder text for the input in the playground + Helper text that appears in the input field of the playground - Description of the parameter (markdown enabled) + The description of what this parameter does (supports markdown formatting) + + \ No newline at end of file diff --git a/integrations/analytics/plausible.mdx b/integrations/analytics/plausible.mdx index 8d65d86a4..eb03a1516 100644 --- a/integrations/analytics/plausible.mdx +++ b/integrations/analytics/plausible.mdx @@ -2,7 +2,7 @@ title: "Plausible" --- -Add your site's domain to `mint.json` to send analytics to Plausible. +To start using Plausible analytics, simply add your website's domain name to your `mint.json` file. @@ -29,4 +29,4 @@ Add your site's domain to `mint.json` to send analytics to Plausible. } ``` - + \ No newline at end of file diff --git a/integrations/privacy/overview.mdx b/integrations/privacy/overview.mdx index 737baebe5..2e8abc3f7 100644 --- a/integrations/privacy/overview.mdx +++ b/integrations/privacy/overview.mdx @@ -1,6 +1,6 @@ --- title: "Privacy Integrations" -description: "Integrate with a data privacy platform" +description: "Add data privacy tools to your documentation" --- @@ -13,9 +13,15 @@ description: "Integrate with a data privacy platform" -## Enabling Data Privacy Integrations +## How to Add Privacy Tools to Your Docs -You can add data privacy platforms onto your docs. Add the `integrations` field into your `mint.json` file with your respective scripts. +Want to add privacy features to your documentation? It's simple! Just follow these steps: + +1. Open your `mint.json` file +2. Add an `integrations` section +3. Include your privacy platform with its source code + +Here's an example of how to add Osano: ```json "integrations": { @@ -23,4 +29,5 @@ You can add data privacy platforms onto your docs. Add the `integrations` field } ``` -If you'd like to request a data privacy platform integration, please let us know in [our community](https://mintlify.com/community). +Need a different privacy tool? Join [our community](https://mintlify.com/community) and let us know what you're looking for! + \ No newline at end of file diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx index 71be4aa65..c41333147 100644 --- a/integrations/support/overview.mdx +++ b/integrations/support/overview.mdx @@ -1,6 +1,6 @@ --- title: "Support Integrations" -description: "Integrate with a support widget" +description: "Add customer support tools to your documentation" --- @@ -35,9 +35,13 @@ horizontal -## Enabling Support Integrations +## Setting Up Customer Support Tools -You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `mint.json` file with your respective app ID. +Want to help your users get support directly from your documentation? You can add support chat widgets to your docs pages. Here's how to do it: + +1. Open your `mint.json` file +2. Add the `integrations` section as shown below +3. Insert your unique ID from your support tool ```json "integrations": { @@ -46,4 +50,4 @@ You can integrate widgets onto your docs for customer support. Add the `integrat } ``` -If you'd like to request a customer support integration, please let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). +Need a different support tool? Let us know what you're looking for by joining [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). \ No newline at end of file diff --git a/list-table.mdx b/list-table.mdx index bbaef913c..c67f4e1a3 100644 --- a/list-table.mdx +++ b/list-table.mdx @@ -1,18 +1,19 @@ --- title: "Lists and Tables" -description: "Display information in lists and tables" +description: "Learn how to organize information using lists and tables" icon: 'list' --- ## Lists -### Ordered List +### Numbered Lists (Ordered Lists) -To create an ordered list, add line items with numbers followed by periods +When you need to show items in a specific order, use numbers followed by a period. Here's an example: 1. First item 2. Second item 3. Third item 4. Fourth item +Here's how to write it: ```md 1. First item 2. Second item @@ -20,15 +21,16 @@ To create an ordered list, add line items with numbers followed by periods 4. Fourth item ``` -### Unordered List +### Bullet Points (Unordered Lists) -To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items +When the order doesn't matter, you can use bullet points. You can create these using any of these symbols: dash (`-`), star (`*`), or plus (`+`). Here's how it looks: - First item - Second item - Third item - Fourth item +Here's how to write it: ```md - First item - Second item @@ -36,53 +38,60 @@ To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (` - Fourth item ``` -### Nested List +### Lists Within Lists (Nested Lists) -Add indents on list items to nest them +You can create sub-points by adding spaces before your bullet points: - First item - Second item - - Additional item - - Additional item + - Sub-point 1 + - Sub-point 2 - Third item +Here's how to write it: ```md - First item - Second item - - Additional item - - Additional item + - Sub-point 1 + - Sub-point 2 - Third item ``` -Lists follow the official [markdown syntax](https://www.markdownguide.org/basic-syntax/#lists-1). +Want to learn more? Check out the official [markdown guide for lists](https://www.markdownguide.org/basic-syntax/#lists-1). ## Tables -| Property | Description | +Tables help organize information in rows and columns. Here's an example: + +| Property | What it means | | -------- | ------------------------------------- | | Name | Full name of user | -| Age | Reported age | -| Joined | Whether the user joined the community | +| Age | How old the user is | +| Joined | Shows if the user is a member or not | -### Creating a table +### How to Make a Table -The Table component follows the official [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables). +Learn more about tables in the official [markdown guide](https://www.markdownguide.org/extended-syntax/#tables). -To add a table, use three or more hyphens (`---`) to create each column's header, and use pipes (`|`) to separate each column. For compatibility, you should also add a pipe on either end of the row. +To create a table: +1. Use pipes (`|`) to separate your columns +2. Add three or more dashes (`---`) under each header +3. Put a pipe at the start and end of each row +Here's how to write the table above: ```md -| Property | Description | +| Property | What it means | | -------- | ------------------------------------- | | Name | Full name of user | -| Age | Reported age | -| Joined | Whether the user joined the community | +| Age | How old the user is | +| Joined | Shows if the user is a member or not | ``` \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..54625d0aa 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,6 +1,6 @@ --- title: "Quickstart" -description: "Start building modern documentation in under five minutes" +description: "Build modern documentation in under five minutes" icon: "rocket" --- @@ -17,20 +17,19 @@ icon: "rocket" ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +Hey there! Let's walk through how to set up, update, and make your documentation amazing with Mintlify. -### Creating the Repository +### Setting Up Your Documentation -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 creates documentation from MDX files (special markdown files) and settings in our [starter kit](https://github.com/mintlify/starter). We use GitHub to keep your docs connected with your code. To begin, you can either: +- Sign up through our [dashboard](https://dashboard.mintlify.com), or +- Copy 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. + To make sure your changes show up automatically, you'll need to install our GitHub app. You can find it in the [dashboard](https://dashboard.mintlify.com/settings) under Settings. Once it's installed correctly, 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) @@ -38,11 +37,10 @@ your docs with your code, and make source control effortless. Onboard through th - - 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) + + Want to keep your docs with your code? No problem! You can: + 1. Move your docs into your code repository + 2. Tell us where to find your `mint.json` file in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) Monorepo setup -### Updating the Content +### Making Changes -Mintlify enables you to easily customize the style, structure, and content of -your docs. +Here's how you can customize your docs to look and work exactly how you want. - + - 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. First, install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you haven't already. + 2. Copy your docs to your computer using `git clone `. New to this? Check out how to set up [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. Open the files in your favorite code editor. + 4. Install our preview tool with `npm i -g mintlify`. - Learn more about this in our [local development guide](/development). + Want more details? Check out our [local development guide](/development). - + - Learn more about how to use the web editor on our [guide](/web-editor). + Find out how to use our web editor in our [guide](/web-editor). - + - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: + You can easily change colors, logos, and buttons in the `mint.json` file. Here are the basics: ```json "name": "Your Company" @@ -101,86 +98,81 @@ your docs. }, ``` - A full list of supported configurations can be found at [global settings](/settings/global). + See all options in our [global settings](/settings/global). - + - Add content with simple MDX files. Initiate your pages with this template: + Create new pages using MDX files. Start each page with: ```md --- title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" + sidebarTitle: "Sidebar title (optional)" + description: "Brief description (optional)" --- ``` - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). + Learn how to add images, tables, and more in our [MDX guide](/text). We also have many [ready-to-use 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). + When you're ready to update your site, save your changes and push them to GitHub. Need help? Here's a [simple guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push). If something goes wrong, you can always update through our [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) - + - You can easily set up your API references using an OpenAPI document. + Want to document your API? It's easy with an 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. + 1. Add your `openapi.yaml` or `openapi.json` file to your docs, or link to it in `mint.json`: ```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. Convert your OpenAPI file into docs pages: ```bash npx @mintlify/scraping@latest openapi-file ``` - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. + 3. Add the new files to your navigation in `mint.json`. - 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). + Need more help? Check out our guides on [setting up OpenAPI](/api-playground/openapi/setup), [API authentication](/api-playground/openapi/writing-openapi), and [manual API docs](/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). + See how people use your docs with our built-in analytics. Find page views, search data, and more in 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). + Want to use other analytics tools? Check out our [supported integrations](/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). + Need help moving your existing docs to Mintlify? Our Enterprise plan includes a full migration service. Interested? [Email us](mailto:sales@mintlify.com). -### Publishing +### Publishing Your Docs - + -Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan. +Want your docs on your website's domain? You can do this for free! -Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain. +Just go to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to set up your 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). +Great job! Your Mintlify docs are ready to go! Need help or have 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 diff --git a/reusable-snippets.mdx b/reusable-snippets.mdx index 0ad0ee9ee..8b4cdd1d6 100644 --- a/reusable-snippets.mdx +++ b/reusable-snippets.mdx @@ -1,35 +1,26 @@ --- title: 'Reusable Snippets' -description: 'Reusable, custom snippets to keep content in sync' +description: 'Save time by creating content pieces you can use over and over' icon: 'recycle' --- -One of the core principles of software development is DRY (Don't Repeat -Yourself), which applies to documentation as -well. If you find yourself repeating the same content in multiple places, you -should create a custom snippet to keep your content in sync. +When writing documentation, it's best not to repeat the same information in multiple places. Instead of copying and pasting the same content, you can create a "snippet" - a reusable piece of content that automatically stays the same everywhere you use it. -## Creating a custom snippet +## Creating a Custom Snippet -**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work. +**Important**: You must save your snippet file in the `snippets` directory for it to work properly. - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a - component. +Any file you put in the `snippets` directory will be treated as a reusable piece of content. These files won't show up as regular pages on your site. To use a snippet, you'll need to import it into another file where you want the content to appear. +### Basic Snippet Creation -### Default export - -1. Add content to your snippet file that you want to re-use. Optionally, you can add variables that can be filled in via props - when you import the snippet. In this example, our variable is word. +1. First, create your snippet with the content you want to reuse: ```typescript snippets/my-snippet.mdx Hello world! This is my content I want to reuse across pages. ``` - -2. Import the snippet into your destination file. +2. Then, add the snippet to any page where you want to use it: ```typescript destination-file.mdx --- @@ -47,16 +38,15 @@ Lorem impsum dolor sit amet. ``` -### Exporting with variables +### Adding Custom Variables to Snippets -1. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word. +1. You can make your snippets more flexible by adding variables. These are spots in your content that can change depending on how you use them: ```typescript snippets/my-snippet.mdx My keyword of the day is {word}. ``` - -2. Import the snippet into your destination file with the variable. The property will fill in based on your specification. +2. When you use the snippet, you can fill in the variable with different content: ```typescript destination-file.mdx --- @@ -74,9 +64,9 @@ Lorem impsum dolor sit amet. ``` -### Reusable variables +### Using Shared Variables -1. Export a variable from your snippet file: +1. You can create variables that you want to use in multiple places: ```typescript snippets/path/to/custom-variables.mdx export const myName = 'my name'; @@ -84,7 +74,7 @@ export const myName = 'my name'; export const myObject = { fruit: 'strawberries' }; ``` -2. Import the snippet from your destination file and use the variable: +2. Then use these variables wherever you need them: ```typescript destination-file.mdx --- @@ -97,10 +87,9 @@ import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; Hello, my name is {myName} and I like {myObject.fruit}. ``` -### Reusable components +### Creating Reusable Components -1. Inside your snippet file, create a component that takes in props by exporting - your component in the form of an arrow function. +1. You can create more complex snippets (called components) that can handle different types of content: ```typescript snippets/custom-component.mdx export const MyComponent = ({ title }) => ( @@ -112,11 +101,10 @@ export const MyComponent = ({ title }) => ( ``` - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. + When creating components this way, you'll need to use HTML-style tags instead of markdown. If you need to use markdown, create a basic snippet instead. -2. Import the snippet into your destination file and pass in the props +2. Use your component by importing it and providing the required information: ```typescript destination-file.mdx --- @@ -131,14 +119,12 @@ Lorem ipsum dolor sit amet. ``` -### Client-Side Content +### Content That Loads in the Browser -By default, Mintlify employs server-side rendering, generating content -at build time. For client-side content loading, ensure to verify the -`document` object's availability before initiating the rendering process. +Most content on your site loads when the page is first built. But sometimes you need content that loads after someone visits your page. Here's how to create that: ```typescript snippets/client-component.mdx -{/* `setTimeout` simulates a React.useEffect, which is called after the component is mounted. */} +{/* This code runs after the page loads in the browser */} export const ClientComponent = () => { if (typeof document === "undefined") { return null; @@ -153,4 +139,4 @@ export const ClientComponent = () => { return
} } -``` +``` \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index d35fd7e3a..1e231ce5b 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -1,48 +1,45 @@ --- title: 'JWT Handshake' -description: 'Use a customized login flow to authenticate users' +description: 'How to set up custom user login for your docs' --- - This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different. + This guide explains how to set up JWT **Authentication** for logging in users. If you're looking for JWT **Personalization** setup instead, check out [this guide](/settings/authentication-personalization/personalization-setup/jwt). -If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL. +Want to use your own login system instead of a dashboard? You can do this by using something called a JWT (JSON Web Token) that gets added to the website URL. This method lets you keep your docs separate from your main dashboard, or work without a dashboard entirely. -## Implementation +## How to Set It Up - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend. + + First, visit your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and create a private key. Think of this like a special password - keep it somewhere safe where only your website's backend can access it. - - Create a login flow that does the following: - - Authenticate the user - - Create a JWT containing the authenticated user's info in the [User](../sending-data) format - - Sign the JWT with the secret key, using the EdDSA algorithm - - Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash + + Create a login process that follows these steps: + - Checks if the user is allowed to log in + - Makes a JWT that contains the user's information (following the [User](../sending-data) format) + - Signs (secures) the JWT using your private key and the EdDSA method + - Creates a link back to your docs that includes the JWT (it should look like: `/login/jwt-callback` plus the JWT) - - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings. + + Go back to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the web address where users will start the login process. -## Example +## Real-World Example -I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs -to be completely separate from my dashboard (or I don’t have a dashboard at all). +Let's say you have documentation at `docs.foo.com` and you want to keep it separate from your main website's dashboard (or maybe you don't have a dashboard at all). -To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a -JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow -for my users. At the end of this login flow, once I have verified the identity of the user, -I create a JWT containing the user’s custom data according to Mintlify’s specification. -I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the -form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user. +Here's what you'll do: +1. Get a JWT secret key from your Mintlify dashboard +2. Create a login page at `https://foo.com/docs-login` +3. After a user successfully logs in, create a JWT with their information +4. Use your secret key to secure the JWT +5. Send the user to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}` +6. Add `https://foo.com/docs-login` to your Mintlify dashboard settings -I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the -Login URL field. - -Here's what the code might look like: +Here's what the code looks like: ```ts TypeScript @@ -100,3 +97,5 @@ async def return_mintlify_auth_status(current_user): return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302) ``` + + \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index d786a042f..cae2864b4 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -1,45 +1,48 @@ --- title: 'OAuth 2.0 Handshake' -description: 'Integrate with your OAuth server to enable user login via the PKCE flow' +description: 'Connect your OAuth server to let users log in using a secure method called PKCE flow' --- - This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different. + This guide explains how to set up OAuth for **Personalization**. If you need to set up OAuth for **Authentication** instead, please check the [OAuth Authentication setup guide](/settings/authentication-personalization/authentication-setup/oauth), as the steps are slightly different. -If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. +If you already have an OAuth server that works with PKCE flow, you can connect it to Mintlify to create an easy login experience for your users. -## Implementation +## How to Set It Up - Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint. + First, make an API endpoint that works with OAuth access tokens. This endpoint should send back user information in a JSON format that matches the [User](../sending-data) requirements. Make sure to note down what permissions (scopes) users need to access this endpoint. - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields: - - - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters. - - **Client ID**: An ID for the OAuth 2.0 client to be used. - - **Scopes**: An array of scopes that will be requested. - - **Token URL**: The base URL for the token exchange request. - - **Info API URL**: The endpoint that will be hit to retrieve user info. + + Visit your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and follow these steps: + 1. Select the OAuth option + 2. Fill out these required fields: + - **Authorization URL**: The main URL where users will start the authorization process + - **Client ID**: Your OAuth 2.0 client's identification number + - **Scopes**: The permissions you want to request from users + - **Token URL**: The URL where access tokens are exchanged + - **Info API URL**: The URL of your endpoint that provides user information - - Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server. + + Find the Redirect URL in your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication). Copy this URL and add it to your OAuth server's list of allowed redirect URLs. ## Example -I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`. +Here's a real-world example to help you understand the setup: -To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification. +Let's say I have an OAuth server and want to set up authentication for my documentation site at `foo.com/docs`. -I then go to the Mintlify dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: +First, I create a user information endpoint at `api.foo.com/docs/user-info`. This endpoint needs an OAuth access token with the `docs-user-info` permission to work, and it sends back user data in the format Mintlify expects. + +Then, I go to the Mintlify dashboard's Personalization settings and enter these details: - **Authorization URL**: `https://auth.foo.com/authorization` - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` - **Scopes**: `['docs-user-info']` - **Token URL**: `https://auth.foo.com/exchange` - **Info API URL**: `https://api.foo.com/docs/user-info` -Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings. +Lastly, I copy the Redirect URL shown in the dashboard and add it to my OAuth server's allowed redirect URLs list. \ No newline at end of file diff --git a/settings/custom-domain.mdx b/settings/custom-domain.mdx index 4fdfecb5f..e390fc2b4 100644 --- a/settings/custom-domain.mdx +++ b/settings/custom-domain.mdx @@ -1,22 +1,22 @@ --- title: 'Custom Domain' -description: "Host your documentation at your website's custom domain" +description: "Host your documentation using your own website address" icon: 'globe' --- -To set up your documentation on a custom domain, you'll need to set your desired custom domain in your Mintlify settings and configure your DNS settings on your domain provider. +Want to show your documentation on your own website address? You'll need to do two things: set up your desired web address in Mintlify's settings and update your DNS settings with your domain provider. - Looking to set up a custom subdirectory like mintlify.com/docs? Find + Want to create a subdirectory like mintlify.com/docs instead? You can find those instructions [here](/advanced/subpath/cloudflare). ## Dashboard Settings -1. Head over to your [dashboard](https://dashboard.mintlify.com) -2. Click on "Settings". -3. Click on "Custom Domain". -4. Enter your desired custom domain. For example, `docs.mintlify.com`. +1. Go to your [dashboard](https://dashboard.mintlify.com) +2. Click on "Settings" +3. Click on "Custom Domain" +4. Type in the web address you want to use. For example, `docs.mintlify.com` DNS -If you are using Cloudflare for your DNS provider, you'll need to have the “full strict” security option enabled for the https setting. +If you use Cloudflare to manage your DNS, make sure to turn on the "full strict" security option in the https settings. -Please [contact support](mailto:sales@mintlify.com) if you don't see the custom domain set up after the above configuration. +Need help? If you've followed these steps and your custom domain isn't working, please [contact our support team](mailto:sales@mintlify.com). \ No newline at end of file diff --git a/text.mdx b/text.mdx index 45cec9193..d730d3d68 100644 --- a/text.mdx +++ b/text.mdx @@ -1,12 +1,12 @@ --- title: "Headers and Text" -description: "Text, title, and styling in standard markdown" +description: "How to format text and titles using markdown" icon: 'heading' --- ## Titles -Best used for section headers. +Use these for main section headings. ```md ## Titles @@ -14,7 +14,7 @@ Best used for section headers. ### Subtitles -Best used for subsection headers. +Use these for smaller section headings within main sections. ```md ### Subtitles @@ -22,44 +22,44 @@ Best used for subsection headers. -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. +When you add a **title** or **subtitle**, it automatically creates a clickable link and appears in the table of contents on the right side. ## Text Formatting -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. +You can format your text in different ways using markdown. Just put certain symbols around your text to change how it looks. -| Style | How to write it | Result | +| Format | What to Type | How it Looks | | ------------- | ----------------- | --------------- | | Bold | `**bold**` | **bold** | | Italic | `_italic_` | _italic_ | | Strikethrough | `~strikethrough~` | ~strikethrough~ | -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. +You can mix these together. For example, type `**_bold and italic_**` to get **_bold and italic_** text. -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. +For small text above or below the line, use HTML tags. Add `` for above or `` for below. -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | +| Type | What to Type | How it Looks | +| ------------ | ----------------------- | --------------------- | +| Above line | `superscript` | superscript | +| Below line | `subscript` | subscript | -## Linking to Pages +## Adding Links -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). +To create a link, put the text in square brackets `[]` and the website address in regular brackets `()`. For example, type `[click here for Google](https://google.com)` to create [click here for Google](https://google.com). -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page "Text" in our components section. +When linking to other pages in your docs, start from the main folder. For example, use `[see our text guide](/content/text)` to link to the "Text" page. -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. +Try not to use shortcuts like `[text guide](../text)` because they load more slowly. -You can validate broken links in your docs with [our CLI](/development). +You can check for broken links using [our CLI tool](/development). ## Blockquotes -### Singleline +### Single Line Quote -To create a blockquote, add a `>` in front of a paragraph. +To make a quote, put a `>` symbol before your text. > Dorothy followed her through many of the beautiful rooms in her castle. @@ -67,7 +67,7 @@ To create a blockquote, add a `>` in front of a paragraph. > Dorothy followed her through many of the beautiful rooms in her castle. ``` -### Multiline +### Multiple Line Quote > Dorothy followed her through many of the beautiful rooms in her castle. > @@ -79,11 +79,11 @@ To create a blockquote, add a `>` in front of a paragraph. > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. ``` -### LaTeX +### Math Equations (LaTeX) -Mintlify supports in-line [LaTeX](https://www.latex-project.org) by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$. +You can write math equations using [LaTeX](https://www.latex-project.org). Put your equation between dollar signs ($). For example, `$(a^2 + b^2 = c^2)$` shows up as $(a^2 + b^2 = c^2)$. -Equations on their own line can be created with double dollar signs (\$\$): +For bigger equations on their own line, use two dollar signs ($$): $$\exists \, x \notin [0,1]$$ @@ -93,7 +93,7 @@ $$\exists \, x \notin [0,1]$$ ### Line Breaks -Markdown syntax also recognizes a double enter in your MDX as a linebreak. +To start a new paragraph, press Enter twice when writing your text. ```html
@@ -103,4 +103,4 @@ Markdown syntax also recognizes a double enter in your MDX as a linebreak. Paragraph 1 Paragraph 2 -``` +``` \ No newline at end of file