diff --git a/advanced/custom/css.mdx b/advanced/custom/css.mdx deleted file mode 100644 index aa28ccd2b..000000000 --- a/advanced/custom/css.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: 'Custom CSS' -description: 'Fully customize your documentation with custom CSS' ---- - - - Custom CSS is available as an add-on to the [Pro plan](https://mintlify.com/pricing). - - -Add any number of CSS files to your repository and the defined class names will be applied and available across all of your MDX files. - -## Adding style.css - -For example, you can add the following `style.css` file to customize the styling of the navbar and footer. - -```css -#navbar { - background: "#fffff2"; - padding: 1rem; -} - -footer { - margin-top: 2rem; -} -``` - -## Using Identifiers - -Mintlify has a set of common identifiers to help you tag important elements of the UI. Some, but not all are listed in the following: - -`#topbar-cta-button` `#navbar` `#sidebar` `#content-area` `#table-of-contents` - - - Use inspect element to find references to elements you're looking to - customize. - - - - References and the styling of common elements are subject to change as the - platform evolves. Please use custom styling with caution. - diff --git a/advanced/custom/js.mdx b/advanced/custom/js.mdx deleted file mode 100644 index 5ce0722f4..000000000 --- a/advanced/custom/js.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 'Custom JS' -description: 'Add JavaScript functionality globally' ---- - - - Custom JS is available as an add-on to the [Pro plan](https://mintlify.com/pricing). - - -Custom JS allows you to add custom executable code globally. It is the equivalent of adding a ` - -``` - -To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react` [package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application: - -```jsx - -``` - -## Usage - -In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props: - -| Prop | Type | Description | -| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- | -| `connection` | [MintlifyWidgetConnectionProps](#mintlifywidgetconnectionProps) | Information needed to connect to our API. Required. | -| `display?` | [MintlifyWidgetDisplayProps](#mintlifywidgetdisplayProps) | Configurations for the widget appearance and interactions. | -| `tracking?` | [MintlifyWidgetTrackingFunctions](#mintlifywidgettrackingfunctions) | Callback functions for tracking analytics. | - -### MintlifyWidgetConnectionProps - -| Prop | Type | Description | -| -------- | -------- | ----------------------------------------------------------- | -| `apiKey` | `string` | Widget API key generated from Mintlify dashboard. Required. | -| `url?` | `string` | Used for internal testing only | - -### MintlifyWidgetDisplayProps - -| Prop | Type | Description | -| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- | -| `trigger?` | [MintlifyWidgetDisplayTriggerProps](#mintlifywidgetdisplaytriggerprops) | Appearance of the trigger. | -| `colors?` | [MintlifyWidgetDisplayColorsProps](#mintlifywidgetdisplaycolorsprops) | Colors used across the widget. | -| `chat?` | [MintlifyWidgetDisplayChatProps](#mintlifywidgetdisplaychatprops) | Configs specific to AI chat. | -| `isDarkMode?` | `boolean` | Controlled dark mode appearance. Defaults to OS preference. | - -#### MintlifyWidgetDisplayTriggerProps - -| Prop | Type | Description | -| ------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `type?` | `'button'`\|`'input'` | Type of the trigger to display. Defaults to `button`. | -| `label?` | `string` | Label displayed in the trigger. Defaults to `Get help` for the button trigger and `Ask anything...` for the input trigger. | -| `buttonIcon?` | `'chat'`\|`'sparkles'`\|`'mintlify'` | Icon used in the trigger. Only available for the `button` trigger. Defaults to `chat`. | -| `iconOnly?` | `boolean` | Only show icon in the trigger or not. Defaults to `false`. | - -Here is an overview of what the trigger looks like with different configurations. - -| `type='input'` | | -| -------------- | ------------------------------------------------------------ | -| | | - -| `type='button'` | `'chat'` | `'sparkles'` | `'mintlify'` | -| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `iconOnly=false` | | | | -| `iconOnly=true` | | | | - -#### MintlifyWidgetDisplayColorsProps - -| Prop | Type | Description | -| --------------- | -------- | -------------------------------------------------------- | -| `primary?` | `string` | Primary color used in the widget. Defaults to `#0D9373`. | -| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`. | - -#### MintlifyWidgetDisplayChatProps - -| Prop | Type | Description | -| ------------------------ | ---------- | ------------------------------------------------------------------ | -| `openCitationInSameTab?` | `boolean` | Open the citation url in the same tab or not. Defaults to `false`. | -| `exampleQueries?` | `string[]` | Example queries to prompt the user to ask. Defaults to `[]`. | - -### MintlifyWidgetTrackingFunctions - -| Prop | Type | Description | -| --------------------- | ------------------------------------------ | -------------------------------------------------- | -| `trackChatEnter` | `()=> void` | Triggered when the user opens the chat widget. | -| `trackCitationClick` | `(title: string, url: string)=> void` | Triggered when the user clicks on a citation. | -| `trackChatThumbsUp` | `(query: string, response: string)=> void` | Triggered when the user thumbs up on a response. | -| `trackChatThumbsDown` | `(query: string, response: string)=> void` | Triggered when the user thumbs down on a response. | -| `trackChatFollowup` | `(query: string)=> void` | Triggered when the user asks a question. | -| `trackChatClose` | `(queriesCount: number)=> void` | Triggered when the user exits the chat widget. | diff --git a/api-playground/mdx/authentication.mdx b/api-playground/mdx/authentication.mdx deleted file mode 100644 index b6469ecb7..000000000 --- a/api-playground/mdx/authentication.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Authentication" -description: "You can set authentication parameters to let users use their real API keys." ---- - -## Enabling Authentication - -You can add an authentication method to your mint.json to enable it on every page or you can set it on a per-page basis. - -The page's authentication method will override mint.json if both are set. - -### Bearer Token - - - -```json mint.json -"api": { - "auth": { - "method": "bearer" - } -} -``` - -```md Page Metadata ---- -title: "Your page title" -authMethod: "bearer" ---- -``` - - - -### Basic Authentication - - - -```json mint.json -"api": { - "auth": { - "method": "basic" - } -} -``` - -```md Page Metadata ---- -title: "Your page title" -authMethod: "basic" ---- -``` - - - -### API Key - - - -```json mint.json -"api": { - "auth": { - "method": "key", - "name": "x-api-key" - } -} -``` - -```md Page Metadata ---- -title: "Your page title" -authMethod: "key" ---- -``` - - - -### None - -The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json. - - -```md Page Metadata ---- -title: "Your page title" -authMethod: "none" ---- -``` - diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx deleted file mode 100644 index 55682df30..000000000 --- a/api-playground/mdx/configuration.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -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 `mint.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. - - - - In your `mint.json` file, define your base URL and auth method: - - ```json - { - "api": { - "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs - "auth": { - "method": "bearer" // 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: - - ```json - { - "api": { - "playground": { - "mode": "hide" - } - } - } - ``` - - Find a full list of API configurations [here](/settings/global#api-configurations). - - - - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: - - ```md - --- - title: 'Create new user' - api: 'POST https://api.mintlify.com/user' - --- - ``` - - You can specify path parameters by adding the parameter name to the path, wrapped with `{}`: - - ```bash - https://api.example.com/v1/endpoint/{userId} - ``` - - - - If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`. - - - - - - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation). - - diff --git a/api-playground/openapi/advanced-features.mdx b/api-playground/openapi/advanced-features.mdx deleted file mode 100644 index a262422b4..000000000 --- a/api-playground/openapi/advanced-features.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Advanced Features" -description: "Support for advanced OpenAPI features" ---- - -OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them 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: - -- `oneOf` functions like an "exclusive-or" operator -- `anyOf` functions like an "or" operator -- `allOf` functions like an "and" operator - -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. - -Mintlify currently does not support the `not` keyword. - -### Combining schemas with `allOf` - -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/). - -```yaml -org_with_users: - allOf: - - $ref: '#/components/schemas/Org' - - type: object - properties: - users: - type: array - description: An array containing all users in the organization -... -components: - schemas: - Org: - type: object - properties: - id: - type: string - description: The ID of the organization -``` - - - - - The ID of the organization - - - An array containing all users in the organization - - - - -### Providing options 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: - -```yaml -delivery_address: - oneOf: - - title: StreetAddress - type: object - properties: - address_line_1: - type: string - description: The street address of the recipient - ... - - title: POBox - type: object - properties: - box_number: - type: string - description: The number of the PO Box - ... -``` - - -
- - - - The street address of the residence - - - - - The number of the PO Box - - - -
- - -## `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: - - - The language of the code sample. - - - - The label for the sample. This is useful when providing multiple examples for a single endpoint. - - - - The source code of the sample. - - -Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. - -```yaml -paths: - /plants: - get: - ... - x-codeSamples: - - lang: bash - label: List all unwatered plants - source: | - planter list -u - - lang: javascript - label: List all unwatered plants - source: | - const planter = require('planter'); - planter.list({ unwatered: true }); - - lang: bash - label: List all potted plants - source: | - planter list -p - - lang: javascript - label: List all potted plants - source: | - const planter = require('planter'); - planter.list({ potted: true }); -``` diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx deleted file mode 100644 index bc24fbbf6..000000000 --- a/api-playground/openapi/setup.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: "OpenAPI Setup" -description: "Reference OpenAPI endpoints in your docs pages" ---- - -## Add an OpenAPI specification 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+. - -## Auto-populate 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. - -**Example with Anchors:** - -```json {5} -{ - "anchors": [ - { - "name": "API Reference", - "openapi": "/path/to/openapi.json", - "url": "api-reference", - "icon": "square-terminal" - } - ] -} -``` - -![](/images/anchors-autogeneration-anchors.png) - -**Example with Tabs:** - -```json {6} -{ - "tabs": [ - { - "name": "API Reference", - "url": "api-reference", - "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" - } - ] -} -``` - -![](/images/autogeneration-with-tabs.png) - -To validate your OpenAPI spec, you can use this command:
`mintlify openapi-check ` - - -When using this option, the metadata for the generated pages will have the following default values: - -* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. - -* `description`: The `description` field from the OpenAPI operation, if present. - -* `version`: The `version` value from the anchor or tab, if present. - -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. - -## Create MDX files for API 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). - -![](/images/elevenlabs-mdx-autogeneration-example.png) - -### Autogenerate files - -For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper. - -Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) -autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the -OpenAPI document in your codebase. - -```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. - -```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. - - -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. - -If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have -only one OpenAPI file - it will automatically detect your OpenAPI file. - - - ```md Example - --- - title: "Get users" - openapi: "/path/to/openapi-1.json GET /users" - --- - ``` - - ```md Format - --- - title: "title of the page" - openapi: openapi-file-path method path - --- - ``` - - -
- - - 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. - - -## Create MDX files for OpenAPI schemas - -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: - - - ```md Example - --- - openapi-schema: OrderItem - --- - ``` - - ```md Format - --- - openapi-schema: "schema-key" - --- - ``` - \ No newline at end of file diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx deleted file mode 100644 index 57cd93680..000000000 --- a/api-playground/openapi/writing-openapi.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Writing OpenAPI" -description: "Use OpenAPI features to enhance your Mintlify docs" ---- - -## Describing your API - -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 - - - 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). - - -## Specifying the URL for your API - -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/). - -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. - -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. - -## Specifying authentication - -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. - -The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. - -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. diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx deleted file mode 100644 index c222ffedf..000000000 --- a/api-playground/overview.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Interactive Playground' -description: 'Enable users to interact with your API' -openapi: 'GET /plants/{id}' -hideApiMarker: true -icon: 'play' ---- - -The API playground is an interactive environment to make requests and preview an API endpoint. - - - Autogenerating API pages with OpenAPI will automatically generate API - playground. Read more about using OpenAPI with Mintlify - [here](/api-playground/openapi). - diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx deleted file mode 100644 index 85504e746..000000000 --- a/api-playground/troubleshooting.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Troubleshooting" -description: "Common issues with API References" -icon: "triangle-exclamation" ---- - -API pages are complicated. As a result, there are a lot of things that can go wrong. -Here's a list of common issues we've seen customers run into: - - - - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, - or your OpenAPI document is invalid. - - Running `mintlify dev` locally should reveal some of these issues. - - To verify your OpenAPI document will pass validation: - - 1. Visit [this validator](https://apitools.dev/swagger-parser/online/) - 2. Switch to the "Validate text" tab - 3. Paste in your OpenAPI document - 4. Click "Validate it!" - - If the text box that appears below has a green border, your document has passed validation. - This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document - passes validation here, there's a great chance the problem is elsewhere. - - Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, - you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3): - - - - - - - - - This is usually caused by a misspelled `openapi` field in the page metadata. Make sure - the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. - - Here's an example of how things might go wrong: - -```md get-user.mdx ---- -openapi: "GET /users/{id}/" ---- -``` - -```yaml openapi.yaml -paths: - "/users/{id}": - get: ... -``` - - Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI - document does not. - - Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document - in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI - documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: - -```md api-reference/v1/users/get-user.mdx ---- -openapi: "v1 GET /users/{id}" ---- -``` - - - - - If you have a custom domain configured, this could be an issue with your reverse proxy. By - default, requests made via the API Playground start with a `POST` request to the - `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` - requests, then all of these requests will fail. To fix this, configure your reverse proxy to - allow `POST` requests to the `/api/request` path. - - Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure - Mintlify to send requests directly to your backend with the `api.playground.disableProxy` - setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will - likely require you to configure CORS on your server, as these requests will now come directly - from your users' browsers. - - - diff --git a/changelog/overview.mdx b/changelog/overview.mdx deleted file mode 100644 index ad2c56f93..000000000 --- a/changelog/overview.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: "Product Updates" -description: "New updates and improvements" -mode: "center" ---- - - ## Authentication - - 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. - - - - - - - - ## AI Assistant - - - 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. - - ## 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. - - ## Web Editor - - - Web Editor - - - We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown. - - Check out our [docs on getting started with Web Editor](/web-editor). - - ## /llms.txt support - - - 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) - - ## Localization - - 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. - - ### Quality 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. - - - - ## Changelogs - - Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users. - - - Changelog - - - ## 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. - - ```javascript Line Highlighting Example {1,3-5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - - ````md - ```javascript Line Highlighting Example {1,3-5} - const greeting = "Hello, World!"; - function sayHello() { - console.log(greeting); - } - sayHello(); - ``` - ```` - - ## Light mode code blocks - - Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`: - - ```json - "codeBlock": { - "mode": "auto" - } - ``` - - ## Advanced Footer - - - 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. - - * Fixed `suggestEdit` not showing up even when enabled. - - * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results. - - * Don't allow search engines to crawl user-auth protected pages. - - * Revalidate the cache when an org is deleted. - - * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages. - - * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions. - - * Add in-line-style support for icons - - * 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. - - - - ## Custom Fonts - - - 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. - - ## Images in Card components - - 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). - - ## Update Speed Performances - - - 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. - - ## SEO improvements - - - 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. - - ## Bug Fixes - - * 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`. - - * Fix relative positioning of the AI widget. - - ## 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) - - - - ## 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 - - 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. - - * [Learn more about API configurations](/settings/global#api-configurations) - - ## Mobile SEO improvements - - We've fixed the mobile layout of our docs so that they are more SEO-friendly - - including adding proper aria tags to elements. - - ## Support Form - - We added a more detailed support form to the Mintlify dashboard. You can now - submit a form to get in touch with us. - - ## Bug Fixes - - * Fixed a bug for the Segment integration functionality. - - * 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. - - - - ## AI 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) - - * [Learn how to install the Widget](/advanced/widget/chat#getting-started) - - ## Pro Plan - - We also updated our pricing plans for better customizability and scale. - - * [Read the blog announcement](https://mintlify.com/blog/pro-plan) - - ## API Playground Code Example Sync - - When you browse API docs, the selected code example now syncs across your pages. - - ## Insights - - 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. - - - - -## 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. - - - - - -## Okta SSO -We now support sign-on via Okta SAML and OIDC. - -## Mintlify REST API -Programmatically rigger updates to your documentation. - - - - - -## 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 - -Check out our [Custom Mode docs](/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). - - - - - -## 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 - - - - - -## 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. - - diff --git a/code.mdx b/code.mdx deleted file mode 100644 index b137fcce0..000000000 --- a/code.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Code Blocks" -description: "Display inline code and code blocks" -icon: 'code' ---- - -## Basic - -### Inline Code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -### Code Block - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` - -Visit the [Code Block page](/content/components/code) for more detailed docs. diff --git a/content/components/accordion-groups.mdx b/content/components/accordion-groups.mdx deleted file mode 100644 index 29f90169c..000000000 --- a/content/components/accordion-groups.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Accordion Groups" -description: "Group multiple accordions into a single display." -icon: "table-rows" ---- - -Simply add `` around your existing `` components. - - - - You can put other components inside Accordions. - - ```java HelloWorld.java - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - - - - - -````jsx Accordion Group Example - - - You can put other components inside Accordions. - - ```java HelloWorld.java - class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } - } - ``` - - - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - - - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. - - -```` - - - -`AccordionGroup` does not have any props. diff --git a/content/components/accordions.mdx b/content/components/accordions.mdx deleted file mode 100644 index f4757be9b..000000000 --- a/content/components/accordions.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Accordions" -description: "A dropdown component to toggle content" -icon: "square-caret-down" ---- - - - You can put any content in here. Check out - [AccordionGroup](/content/components/accordion-groups) if you want to group - multiple Accordions into a single display. - - - - -```jsx Accordion Example - - You can put any content in here. - -``` - - - -## Props - - - Title in the Accordion preview. - - - - Detail below the title in the Accordion preview. - - - - Whether the Accordion is open by default. - - - - A [Font Awesome icon](https://fontawesome.com/icons) or SVG code - - - - One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or - "brands" - diff --git a/content/components/callouts.mdx b/content/components/callouts.mdx deleted file mode 100644 index 32cc7f082..000000000 --- a/content/components/callouts.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 'Callout Boxes' -description: 'Use callouts to add eye-catching context to your content' -icon: 'circle-exclamation' ---- - -### Note Callouts - -This adds a note in the content - -```jsx -This adds a note in the content -``` - -### Warning Callouts - -This raises a warning to watch out for - -```jsx -This raises a warning to watch out for -``` - -### Info Callouts - -This draws attention to important information - -```jsx -This draws attention to important information -``` - -### Tip Callouts - -This suggests a helpful tip - -```jsx -This suggests a helpful tip -``` - -### Check Callouts - -This brings us a checked status - -```jsx -This brings us a checked status -``` diff --git a/content/components/card-groups.mdx b/content/components/card-groups.mdx deleted file mode 100644 index 851933802..000000000 --- a/content/components/card-groups.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 'Card Groups' -description: 'Show cards side by side in a grid format' -icon: 'rectangles-mixed' ---- - -The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards on the same column. - - - - Neque porro quisquam est qui dolorem ipsum quia dolor sit amet - - - Lorem ipsum dolor sit amet, consectetur adipiscing elit - - - Ut enim ad minim veniam, quis nostrud exercitation ullamco - - - Excepteur sint occaecat cupidatat non proident - - - - - -```jsx Card Group Example - - - Neque porro quisquam est qui dolorem ipsum quia dolor sit amet - - - Lorem ipsum dolor sit amet, consectetur adipiscing elit - - - Ut enim ad minim veniam, quis nostrud exercitation ullamco - - - Excepteur sint occaecat cupidatat non proident - - -``` - - - -## Props - - - The number of columns per row - diff --git a/content/components/cards.mdx b/content/components/cards.mdx deleted file mode 100644 index f1254e439..000000000 --- a/content/components/cards.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Cards" -description: "Highlight main points or links with customizable icons" -icon: "rectangle" ---- - - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Card Group page. - - - - -```jsx Card Example - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Card Group page. - -``` - -```jsx Image Card Example - - Here is an example of a card with an image - -``` - - - -### Horizontal Card - -Add a `horizontal` property to a card to make it horizontally displayed. - - - Here is an example of a horizontal card - - -### Image Card - -Add an `img` property to a card to display an image on the top of the card. - - - Here is an example of a card with an image - - -## Props - - - The title of the card - - - - A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` - - - - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` - - - - The color of the icon as a hex code - - - - The url that clicking on the card would navigate the user to - - - - Makes the card more compact and horizontal - - - - The url or local path to an image to display on the top of the card - diff --git a/content/components/code-groups.mdx b/content/components/code-groups.mdx deleted file mode 100644 index c6e1b82aa..000000000 --- a/content/components/code-groups.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Code Groups" -description: "The CodeGroup component lets you combine code blocks in a display separated by tabs" -icon: "rectangle-code" ---- - -You will need to make [Code Blocks](/content/components/code) then add the `` component around them. Every Code Block must have a filename because we use the names for the tab buttons. - -See below for an example of the end result. - - - -```javascript helloWorld.js -console.log("Hello World"); -``` - -```python hello_world.py -print('Hello World!') -``` - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - - - - - -````md Code Group Example - - -```javascript helloWorld.js -console.log("Hello World"); -``` - -```python hello_world.py -print('Hello World!') -``` - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - - -```` - diff --git a/content/components/code.mdx b/content/components/code.mdx deleted file mode 100644 index d59351bb4..000000000 --- a/content/components/code.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Code Blocks" -description: "Display code with optional syntax highlighting" -icon: "code" ---- - - - -````md Code Block Example -```javascript Code Block Example -const hello = "world"; -``` -```` - - - -## Basic Code Block - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. - -``` -helloWorld(); -``` - -````md -``` -helloWorld(); -``` -```` - -## Syntax Highlighting - -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. - -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` - -## Names - -You can add more text 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. - -```javascript Code Block Example -const hello = "world"; -``` - -````md Code Block Example -```javascript Code Block Example -const hello = "world"; -``` -```` - -## Line Highlighting - -You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. - -```javascript Line Highlighting Example {1,3-5} -const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); -} -sayHello(); -``` - -````md -```javascript Line Highlighting Example {1,3-5} -const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); -} -sayHello(); -``` -```` - -## Code Groups - -Want to display multiple code examples in one code box? Check out the Code Group docs: - - - Read the reference for the Code Group component - diff --git a/content/components/expandables.mdx b/content/components/expandables.mdx deleted file mode 100644 index dc98a8d73..000000000 --- a/content/components/expandables.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Expandables" -description: "Toggle to display nested properties." -icon: "caret-down" ---- - - - - - - The full name of the user - - - - Whether the user is over 21 years old - - - - - - - -```jsx Expandable Example - - - - The full name of the user - - - - Whether the user is over 21 years old - - - -``` - - - -## Props - - - The name of the object you are showing. Used to generate the "Show NAME" and - "Hide NAME" text. - - - - Set to true to show the component as open when the page loads. - diff --git a/content/components/frames.mdx b/content/components/frames.mdx deleted file mode 100644 index 66a24cdf0..000000000 --- a/content/components/frames.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Frames" -description: "Use the Frame component to wrap images or other components in a container." -icon: "frame" ---- - -Frames are very helpful if you want to center an image. - - - - - -## Captions - -You can add additional context to an image using the optional `caption` prop. - - - - - -## Props - - - Optional caption text to show centered under your component. - - - - -```jsx Frame - - - -``` - -```jsx Frame with Captions - - - -``` - - diff --git a/content/components/icons.mdx b/content/components/icons.mdx deleted file mode 100644 index ad272ac02..000000000 --- a/content/components/icons.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Icons" -description: "Use [Font Awesome](https://fontawesome.com/icons) icons anywhere in the doc" -icon: "icons" ---- - - - - - -```jsx Icon Example - -``` - - -## Inline Icons - -The icon will be placed inline when used in a paragraph. - -```markdown Inline Icon Example - The documentation you want, effortlessly -``` - - The documentation you want, effortlessly - -## Props - - - A [Font Awesome](https://fontawesome.com/icons) icon - - - - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` - - - - The color of the icon as a hex code (e.g., `#FF5733`) - - - - The size of the icon in pixels - diff --git a/content/components/mermaid-diagrams.mdx b/content/components/mermaid-diagrams.mdx deleted file mode 100644 index 1334bde52..000000000 --- a/content/components/mermaid-diagrams.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 'Mermaid Diagrams' -description: 'Display diagrams using Mermaid' -icon: 'diagram-project' ---- - - - -````md Mermaid Flowchart Example -```mermaid - flowchart LR - subgraph subgraph1 - direction TB - top1[top] --> bottom1[bottom] - end - subgraph subgraph2 - direction TB - top2[top] --> bottom2[bottom] - end - %% ^ These subgraphs are identical, except for the links to them: - - %% Link *to* subgraph1: subgraph1 direction is maintained - outside --> subgraph1 - %% Link *within* subgraph2: - %% subgraph2 inherits the direction of the top-level graph (LR) - outside ---> top2 -``` -```` - - - -[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. - -```mermaid - flowchart LR - subgraph subgraph1 - direction TB - top1[top] --> bottom1[bottom] - end - subgraph subgraph2 - direction TB - top2[top] --> bottom2[bottom] - end - %% ^ These subgraphs are identical, except for the links to them: - - %% Link *to* subgraph1: subgraph1 direction is maintained - outside --> subgraph1 - %% Link *within* subgraph2: - %% subgraph2 inherits the direction of the top-level graph (LR) - outside ---> top2 -``` - -You can create the following using Mermaid diagrams: - -- Flowchart -- Sequence diagram -- Class diagram -- State diagram -- Entity relationship diagram -- User journey -- and more - -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). - -## Syntax for Mermaid diagrams - -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. - -````md -```mermaid -// Your mermaid code block here -``` -```` diff --git a/content/components/params.mdx b/content/components/params.mdx deleted file mode 100644 index e9e1249b9..000000000 --- a/content/components/params.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Parameter Fields" -description: "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). - - - An example of a parameter field - - - - -```jsx Path Example - - An example of a parameter field - -``` - -```jsx Query Example - - The filtering command used to sort through the users - -``` - -```jsx Body Example - - The age of the user. Cannot be less than 0 - -``` - - - -## Props - - - Whether it is a query, path, body, or header parameter followed by the name - - - - Expected type of the parameter's value - - - - Indicate whether the parameter is required - - - - Indicate whether the parameter is deprecated - - - - Default value used by the server if the request does not provide a value - - - - Value that will be used to initialize the playground - - - - Placeholder text for the input in the playground - - - - Description of the parameter (markdown enabled) - diff --git a/content/components/responses.mdx b/content/components/responses.mdx deleted file mode 100644 index bde833629..000000000 --- a/content/components/responses.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'Response Fields' -description: 'Display API response values' -icon: 'message' ---- - -The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something. - - - A response field example - - - - -```jsx ResponseField Example - - A response field example - -``` - - - -## Props - - - The name of the response value. - - - - Expected type of the response value - - - - The default value. - - - - Show "required" beside the field name. - diff --git a/content/components/steps.mdx b/content/components/steps.mdx deleted file mode 100644 index 09700a488..000000000 --- a/content/components/steps.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 'Steps' -description: 'Sequence content using the Steps component' -icon: 'arrow-progress' ---- - -Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. - - - - These are instructions or content that only pertain to the first step. - - - These are instructions or content that only pertain to the second step. - - - These are instructions or content that only pertain to the third step. - - - - - -```jsx Steps Example - - - These are instructions or content that only pertain to the first step. - - - These are instructions or content that only pertain to the second step. - - - These are instructions or content that only pertain to the third step. - - -``` - - - -## Steps Props - - - A list of `Step` components. - - - - The size of the step titles. One of `p`, `h2` and `h3`. - - -## Individual Step Props - - - The content of a step either as plain text, or components. - - - - A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` - - - - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` - - - - The title is the primary text for the step and shows up next to the indicator. - - - - The number of the step. - - - - The size of the step titles. One of `p`, `h2` and `h3`. - diff --git a/content/components/sticky-examples.mdx b/content/components/sticky-examples.mdx deleted file mode 100644 index b44d3ba8a..000000000 --- a/content/components/sticky-examples.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Sidebar Code Examples" -description: "Display code blocks at the top-right of the page on desktop devices" -icon: "sidebar-flip" ---- - -The `` and `` stick code blocks to the top-right of a page even as you scroll. The components work on all pages even if you don't use an API playground. - -`` and `` show up like regular code blocks on mobile. - -## Request Example - -The `` component works similar to [CodeGroup](/content/components/code-groups), but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside ``. - -Please set a name on every code block you put inside RequestExample. - - -````md RequestExample Example - - -```bash Request - curl --request POST \ - --url https://dog-api.kinduff.com/api/facts -``` - - -```` - - -## Response Example - -The `` component is the same as `` but will show up underneath it. - - -````md ResponseExample Example - - -```json Response -{ "status": "success" } -``` - - -```` - diff --git a/content/components/tabs.mdx b/content/components/tabs.mdx deleted file mode 100644 index 255920e05..000000000 --- a/content/components/tabs.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'Tabs' -description: 'Toggle content using the Tabs component' -icon: 'window-restore' ---- - -You can add any number of tabs. - - - - ☝️ Welcome to the content that you can only see inside the first Tab. - - - ✌️ Here's content that's only inside the second Tab. - - - 💪 Here's content that's only inside the third Tab. - - - - - -```jsx Tabs Example - - - ☝️ Welcome to the content that you can only see inside the first Tab. - - - ✌️ Here's content that's only inside the second Tab. - - - 💪 Here's content that's only inside the third Tab. - - -``` - - - -## Tab Props - - - The title of the tab. Short titles are easier to navigate. - diff --git a/content/components/tooltips.mdx b/content/components/tooltips.mdx deleted file mode 100644 index 491f76b4f..000000000 --- a/content/components/tooltips.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Tooltips' -description: 'Show a definition when you hover over text.' -icon: 'message-lines' ---- - -Hover over me and see a tooltip in action - - - -```jsx Tooltip Example -Hover over me -``` - - diff --git a/content/components/update.mdx b/content/components/update.mdx deleted file mode 100644 index f2bad5866..000000000 --- a/content/components/update.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Update" -description: "Keep track of changes and updates" -icon: "rectangle-history" ---- - -The `Update` component is used to keep track of changes and updates. - - - - - - - ## Changelog - - You can add anything here, like a screenshot, a code snippet, or a list of changes. - - #### Features - - Responsive design - - Sticky section for each changelog - - - - ### How to use - ```md - - This is how you use a changelog with a label - and a description. - - - This is how you use a changelog with a label - and a description. - - ``` - - You can use multiple `Update` components to create changelogs. - - - - Each `label` creates an anchor and also shows up on the table of contents on the right. - - -## Props - - - Label in the changelog, on the sticky left side. - - - - Description below the label in the Changelog preview. - diff --git a/development.mdx b/development.mdx deleted file mode 100644 index 856629aaf..000000000 --- a/development.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 'Local Development' -description: 'Preview changes locally to update your docs' ---- - - - -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - - - -**Step 1**: Install Mintlify: - - - - ```bash npm - npm i -g mintlify - ``` - - ```bash yarn - yarn global add mintlify - ``` - - ```bash pnpm - pnpm add -g mintlify - ``` - - - -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: - -```bash -mintlify dev -``` - -Alternatively, if you do not want to install Mintlify globally you can use a run script available: - - - ```bash npm - npx mintlify dev - ``` - - ```bash yarn - yarn dlx mintlify dev - ``` - - ```bash pnpm - pnpm dlx mintlify dev - ``` - - - - - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. - - -A local preview of your documentation will be available at `http://localhost:3000`. - -### Custom Ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: - -```bash -mintlify dev --port 3333 -``` - -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` - -## Mintlify Versions - -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: - - - - ```bash npm - npm i -g mintlify@latest - ``` - - ```bash yarn - yarn global upgrade mintlify - ``` - - ```bash pnpm - pnpm up --global mintlify - ``` - - - -## Validating Links - -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: - -```bash -mintlify broken-links -``` - -## Deployment - -If the deployment is successful, you should see the following: - - - - - -## Code Formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting - - - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` - - - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. - - diff --git a/image-embeds.mdx b/image-embeds.mdx deleted file mode 100644 index 5c12f772b..000000000 --- a/image-embeds.mdx +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: 'Images, Videos, and Embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' ---- - - - - - Mintlify supports files up to 5 MB. To use larger files, consider a storage - service like Cloudinary and embed in your Mintlify documentation. - - -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code - -```md -![title](/path/image.jpg) -``` - -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using Embeds - -To get more customizability with images, you can also use embeds to add images. - -```html - -``` - -### Disable Image Zoom - -To disable the default zoom on click for images, add the noZoom property to image embeds. - -```html - -``` - -### Linking Images - -To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor. - -```html - - - -``` - -### Dark Mode - -To use separate images for light and dark mode, use Tailwind CSS to hide and show images. - -```html - - -``` - -### Related - -For more information, we recommend the following sections: - - - Read the reference for the Frame component - - -## Videos - - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -For YouTube videos use: - -```html - -``` - -For other videos, use: - -```html - -``` - -To autoplay the video, use: - -```html - -``` - - -Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to -be written in camelCase: autoPlay, playsInline. - - -## iFrames - -Loads another HTML page within the document. - -```html - -``` - - - Although not required, we recommend adding the `alt` and `title` attributes to - images for better SEO and accessability. Learn more at [image - SEO](https://yoast.com/image-seo-alt-tag-and-title-tag-optimization/). - diff --git a/list-table.mdx b/list-table.mdx deleted file mode 100644 index bbaef913c..000000000 --- a/list-table.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Lists and Tables" -description: "Display information in lists and tables" -icon: 'list' ---- -## Lists -### Ordered List - -To create an ordered list, add line items with numbers followed by periods - -1. First item -2. Second item -3. Third item -4. Fourth item - -```md -1. First item -2. Second item -3. Third item -4. Fourth item -``` - -### Unordered List - -To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items - -- First item -- Second item -- Third item -- Fourth item - -```md -- First item -- Second item -- Third item -- Fourth item -``` - -### Nested List - -Add indents on list items to nest them - -- First item -- Second item - - Additional item - - Additional item -- Third item - -```md -- First item -- Second item - - Additional item - - Additional item -- Third item -``` - - - -Lists follow the official [markdown syntax](https://www.markdownguide.org/basic-syntax/#lists-1). - - - -## Tables - -| Property | Description | -| -------- | ------------------------------------- | -| Name | Full name of user | -| Age | Reported age | -| Joined | Whether the user joined the community | - - -### Creating a table - - - -The Table component follows the official [markdown syntax](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. - -```md -| Property | Description | -| -------- | ------------------------------------- | -| Name | Full name of user | -| Age | Reported age | -| Joined | Whether the user joined the community | -``` \ No newline at end of file diff --git a/migration.mdx b/migration.mdx deleted file mode 100644 index 491e89454..000000000 --- a/migration.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: 'Migration' -description: 'How to migrate documentation from your existing provider' -icon: 'arrow-up-from-bracket' ---- - -You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to scrape documentation frameworks to Mintlify. - -We currently support migration for: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -} /> - - -} /> - - -} /> - - -Don't see your docs provider or have a home grown system? We can still help! Please get in touch at sales@mintlify.com. - -## Commands - -- `mintlify-scrape section [url]` - Scrapes multiple pages in a site. -- `mintlify-scrape page [url]` - Scrapes a single page in a site. - - -The commands will automatically detect the framework. - -## 🚀 Installation - -First, install the package: - -``` -npm i @mintlify/scraping -``` - -One-time use: - -```bash Section -npx @mintlify/scraping@latest section [url] -``` - -```bash Page -npx @mintlify/scraping@latest page [url] -``` - - -Global installation: - -``` -npm install @mintlify/scraping@latest -g -``` - -Global usage: - - -```bash Section -mintlify-scrape section [url] -``` - -```bash Page -mintlify-scrape page [url] -``` - - -Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. - - -``` -mintlify-scrape openapi-file [openApiFilename] - --w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true] --o, --outDir The folder in which to write any created frontmatter files [string] -``` \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..f4a229dbf 100644 --- a/mint.json +++ b/mint.json @@ -1,41 +1,41 @@ { - "$schema": "https://mintlify.com/schema.json", - "name": "Mintlify", + "$schema": "settings/authentication", + "name": "settings/authentication", "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg", - "href": "https://mintlify.com" + "light": "settings/authentication", + "dark": "settings/authentication", + "href": "settings/authentication" }, - "layout": "sidenav", - "favicon": "/favicon.svg", + "layout": "settings/authentication", + "favicon": "settings/authentication", "sidebar": { - "items": "border" + "items": "settings/authentication" }, "colors": { - "primary": "#0D9373", - "light": "#55D799", - "dark": "#0D9373" + "primary": "settings/authentication", + "light": "settings/authentication", + "dark": "settings/authentication" }, "api": { "auth": { - "method": "bearer" + "method": "settings/authentication" } }, "background": { - "style": "windows" + "style": "settings/authentication" }, "topbarLinks": [ { - "name": "Community", - "url": "https://mintlify.com/community" + "name": "settings/authentication", + "url": "settings/authentication" } ], "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/start" + "name": "settings/authentication", + "url": "settings/authentication" }, "codeBlock": { - "mode": "auto" + "mode": "settings/authentication" }, "feedback": { "thumbsRating": true, @@ -43,57 +43,46 @@ }, "tabs": [ { - "name": "Components", - "url": "content" + "name": "settings/authentication", + "url": "settings/authentication" }, { - "name": "Integrations", - "url": "integrations" + "name": "settings/authentication", + "url": "settings/authentication" }, { - "name": "Changelog", - "url": "changelog" + "name": "settings/authentication", + "url": "settings/authentication" } ], "navigation": [ { - "group": "Getting Started", + "group": "settings/authentication", "pages": [ - "quickstart", + "settings/authentication", { - "group": "Editing", - "icon": "pen-paintbrush", - "pages": [ - "development", - "web-editor" - ] + "group": "settings/authentication", + "icon": "settings/authentication", + "pages": [] }, - "settings/global", - "settings/navigation", "migration" ] }, { - "group": "Writing Content", + "group": "settings/authentication", "pages": [ - "page", - "text", + "settings/authentication", "image-embeds", - "list-table", - "code", "reusable-snippets" ] }, { - "group": "API References", + "group": "settings/authentication", "pages": [ - "api-playground/overview", { - "group": "OpenAPI", - "icon": "brackets-curly", + "group": "settings/authentication", + "icon": "settings/authentication", "pages": [ - "api-playground/openapi/setup", - "api-playground/openapi/writing-openapi", "api-playground/openapi/advanced-features" ] }, @@ -104,49 +93,36 @@ "api-playground/mdx/configuration", "api-playground/mdx/authentication" ] - }, - "api-playground/troubleshooting" + } ] }, { - "group": "Configurations", + "group": "settings/authentication", "pages": [ - "settings/custom-domain", - "settings/seo", "settings/broken-links", "settings/versioning", - "settings/add-members", - "settings/github", "settings/gitlab", "settings/preview-deployments" ] }, { - "group": "Advanced", + "group": "settings/authentication", "pages": [ { - "icon": "code", - "group": "Custom Scripts", - "pages": [ - "advanced/custom/css", - "advanced/custom/js" - ] + "group": "settings/authentication", + "pages": [] }, { - "icon": "folder", - "group": "Custom Subdirectory", + "icon": "settings/authentication", + "group": "settings/authentication", "pages": [ - "advanced/subpath/cloudflare", - "advanced/subpath/route53-cloudfront", "advanced/subpath/vercel" ] }, { - "icon": "user-lock", - "group": "Auth & Personalization", + "icon": "settings/authentication", + "group": "settings/authentication", "pages": [ - "settings/authentication-personalization/authentication", - "settings/authentication-personalization/personalization", "settings/authentication-personalization/authentication-vs-personalization", { "group": "Authentication Setup", @@ -159,35 +135,26 @@ ] }, { - "group": "Personalization Setup", + "group": "settings/authentication", "pages": [ - "settings/authentication-personalization/personalization-setup/choosing-a-handshake", - "settings/authentication-personalization/personalization-setup/shared-session", "settings/authentication-personalization/personalization-setup/jwt", "settings/authentication-personalization/personalization-setup/oauth" ] - }, - "settings/authentication-personalization/sending-data" + } ] }, { - "icon": "plug", - "group": "Extensions", - "pages": [ - "advanced/widget/chat" - ] + "icon": "settings/authentication", + "group": "settings/authentication", + "pages": [] }, { - "icon": "brackets-curly", - "group": "REST API", + "icon": "settings/authentication", + "group": "settings/authentication", "pages": [ - "advanced/rest-api/overview", { - "group": "Updates", - "pages": [ - "advanced/rest-api/update/trigger", - "advanced/rest-api/update/status" - ] + "group": "settings/authentication", + "pages": [] }, { "group": "Discovery API", @@ -201,149 +168,137 @@ ] }, { - "group": "Analytics", + "group": "settings/authentication", "pages": [ - "integrations/analytics/overview", - "integrations/analytics/amplitude", - "integrations/analytics/clearbit", - "integrations/analytics/fathom", - "integrations/analytics/google-analytics", - "integrations/analytics/google-tag-manager", - "integrations/analytics/heap", - "integrations/analytics/hotjar", - "integrations/analytics/koala", - "integrations/analytics/logrocket", - "integrations/analytics/mixpanel", - "integrations/analytics/pirsch", - "integrations/analytics/plausible", - "integrations/analytics/posthog" + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication", + "settings/authentication" ] }, { - "group": "SDKs", + "group": "settings/authentication", "pages": [ - "integrations/sdks/speakeasy", - "integrations/sdks/stainless" + "settings/authentication", + "settings/authentication" ] }, { - "group": "Support", + "group": "settings/authentication", "pages": [ - "integrations/support/overview", - "integrations/support/intercom", - "integrations/support/front" + "settings/authentication", + "settings/authentication", + "settings/authentication" ] }, { - "group": "Privacy", + "group": "settings/authentication", "pages": [ - "integrations/privacy/overview", - "integrations/privacy/osano" + "settings/authentication", + "settings/authentication" ] }, { - "group": "Components", + "group": "settings/authentication", "pages": [ - "content/components/accordions", - "content/components/accordion-groups", "content/components/callouts", "content/components/cards", - "content/components/card-groups", - "content/components/code", "content/components/code-groups", "content/components/frames", - "content/components/icons", - "content/components/mermaid-diagrams", "content/components/steps", - "content/components/tabs", - "content/components/tooltips", - "content/components/update" + "content/components/tabs" ] }, { - "group": "API Components", + "group": "settings/authentication", "pages": [ - "content/components/params", - "content/components/responses", "content/components/expandables", "content/components/sticky-examples" ] }, { - "group": "Changelog", - "pages": [ - "changelog/overview" - ] + "group": "settings/authentication", + "pages": [] } ], "footer": { "socials": { - "x": "https://x.com/mintlify", - "linkedin": "https://www.linkedin.com/company/mintlify", - "github": "https://github.com/mintlify", - "slack": "https://mintlify.com/community" + "x": "settings/authentication", + "linkedin": "settings/authentication", + "github": "settings/authentication", + "slack": "settings/authentication" }, "links": [ { - "title": "Resources", + "title": "settings/authentication", "links": [ { - "label": "Customers", - "url": "https://mintlify.com/customers" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Enterprise", - "url": "https://mintlify.com/enterprise" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Request Preview", - "url": "https://mintlify.com/preview" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Integrations", - "url": "https://mintlify.com/docs/integrations/analytics/overview" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Templates", - "url": "https://github.com/mintlify/themes" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Wall of Love", - "url": "https://mintlify.com/love" + "label": "settings/authentication", + "url": "settings/authentication" } ] }, { - "title": "Company", + "title": "settings/authentication", "links": [ { - "label": "Careers", - "url": "https://mintlify.com/careers" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Blog", - "url": "https://mintlify.com/blog" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Public Roadmap", - "url": "https://feedback.mintlify.com/roadmap" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Security", - "url": "https://mintlify.com/security/responsible-disclosure" + "label": "settings/authentication", + "url": "settings/authentication" } ] }, { - "title": "Legal", + "title": "settings/authentication", "links": [ { - "label": "Privacy Policy", - "url": "https://mintlify.com/legal/privacy" + "label": "settings/authentication", + "url": "settings/authentication" }, { - "label": "Terms of Service", - "url": "https://mintlify.com/legal/terms" + "label": "settings/authentication", + "url": "settings/authentication" } ] } @@ -351,10 +306,10 @@ }, "analytics": { "ga4": { - "measurementId": "G-RCYWHL7EQ7" + "measurementId": "settings/authentication" }, "koala": { - "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" + "publicApiKey": "settings/authentication" } } } \ No newline at end of file diff --git a/page.mdx b/page.mdx deleted file mode 100644 index 1f33697e9..000000000 --- a/page.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "Page Titles and Metadata" -description: "Setting the title and metadata for navigation and SEO" -icon: 'text-size' ---- - -## The Basics - -Each page is an MDX file that should begin with the following metadata syntax -with `---` at the start and end: - - - -```md Schema ---- -title: "title of the page" ---- -``` - -```md Example ---- -title: "Page" ---- -``` - - - -
- - - Mintlify will use the name of the file if you forget to include a title. - - -Other metadata goes in between the same `---` lines. For example, this page uses -this metadata: - -```md ---- -title: "Page Titles and Metadata" -description: "Setting the title and metadata for navigation and SEO" ---- -``` - -## API Pages - -API pages let you build interactive API playgrounds. To create an API page, you -must set an `api` or `openapi` property in the page metadata. - -Learn more about API playgrounds in [our demo](/api-playground). - - - -```md Schema -api or openapi: method endpoint -``` - -```md API Example -api: "GET /users" -``` - -```md OpenAPI Example -openapi: "GET /users" -``` - - - -## Descriptions - -You can show a description that shows directly under the title with the -`description` metadata. - -```md -description: "Your description goes here." -``` - -## Sidebar Title - -You can show a different title in the navigation with the `sidebarTitle` -metadata. This is useful if your title is long and you want something shorter in -the navigation links. - -```md ---- -title: "Your very long page title you want to shorten" -sidebarTitle: "Short title" ---- -``` - -## Sidebar Icons - -Want an icon for your sidebar item like the ones in -[components](/content/components/accordions)? You can set an `icon` attribute in -the metadata! All icons from [Font Awesome](https://fontawesome.com/icons) are -available for us. You can also set an icon type (optional). If not set, the icon -type will be regular. - -```md ---- -title: "Code Block" -icon: "rectangle-code" -iconType: "solid" ---- -``` - -## Page Mode - -The Page Mode setting allows you to customize the appearance of your page. You can choose from -different modes to adjust the layout according to your needs. If no mode is specified, the page -will use the default settings. - -### No Mode - -If no specific mode is given, the page will default to standard settings. This means the page -will display with the default table of contents (if headings are present) and other standard -elements, providing a typical layout without any special adjustments. - -```md ---- -title: "Page with no ToC" ---- -``` - -### Wide Mode - -In *Wide Mode*, you can hide the table of contents (ToC) on the right side of the page. This is -particularly useful if your page doesn’t have any headings or if you prefer to utilize the -extra horizontal space for other content. - -```md ---- -title: "Page with no ToC" -mode: "wide" ---- -``` - -### Custom Mode - -*Custom Mode* provides a minimalist layout by removing all elements except for the top bar. -This mode offers a blank canvas, which is ideal for creating a "landing page" or any page where -you want a clean, distraction-free environment. - - -```md ---- -mode: "custom" ---- -``` - -### Center Mode - -*Center Mode* removes the sidebar and the table of contents, and centers the page content. This mode is great for changelogs -or any page where you want to focus on the content. - - -```md ---- -mode: "center" ---- -``` - -## External Links - -If you want the sidebar to open an external URL, you can set the `url` metadata -in any page. - -```md ---- -title: "Page that goes to external link" -url: "https://www.npmjs.com/package/mintlify" ---- -``` - -## Search Engine Optimization - -You can set meta tags like the image set when shared on social media by passing -them into your page's metadata. Meta tags with colons need to be wrapped in -quotes. - -```md -"twitter:image": "/images/your-photo.jpg" -``` - -See [our SEO page](/settings/seo) for all supported meta tags. diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..22fb45499 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -72,8 +72,6 @@ your docs. 3. Use your favorite IDE to open the repository. 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. - Learn more about this in our [local development guide](/development). - @@ -183,4 +181,4 @@ Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/setting 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). +[support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file diff --git a/reusable-snippets.mdx b/reusable-snippets.mdx deleted file mode 100644 index 0ad0ee9ee..000000000 --- a/reusable-snippets.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: 'Reusable Snippets' -description: 'Reusable, custom snippets to keep content in sync' -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. - -## Creating a custom snippet - -**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work. - - 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. - - -### 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. - -```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. - -```typescript destination-file.mdx ---- -title: My title -description: My Description ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## Header - -Lorem impsum dolor sit amet. - - - -``` - -### Exporting with variables - -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. - -```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. - -```typescript destination-file.mdx ---- -title: My title -description: My Description ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## Header - -Lorem impsum dolor sit amet. - - - -``` - -### Reusable variables - -1. Export a variable from your snippet file: - -```typescript snippets/path/to/custom-variables.mdx -export const myName = 'my name'; - -export const myObject = { fruit: 'strawberries' }; -``` - -2. Import the snippet from your destination file and use the variable: - -```typescript destination-file.mdx ---- -title: My title -description: My Description ---- - -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; - -Hello, my name is {myName} and I like {myObject.fruit}. -``` - -### 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. - -```typescript snippets/custom-component.mdx -export const MyComponent = ({ title }) => ( -
-

{title}

-

... snippet content ...

-
-); -``` - - - 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. - - -2. Import the snippet into your destination file and pass in the props - -```typescript destination-file.mdx ---- -title: My title -description: My Description ---- - -import { MyComponent } from '/snippets/custom-component.mdx'; - -Lorem ipsum dolor sit amet. - - -``` - -### Client-Side Content - -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. - -```typescript snippets/client-component.mdx -{/* `setTimeout` simulates a React.useEffect, which is called after the component is mounted. */} -export const ClientComponent = () => { - if (typeof document === "undefined") { - return null; - } else { - setTimeout(() => { - const clientComponent = document.getElementById("client-component"); - if (clientComponent) { - clientComponent.innerHTML = "Hello, client-side component!"; - } - }, 1); - - return
- } -} -``` diff --git a/settings/add-members.mdx b/settings/add-members.mdx deleted file mode 100644 index 3db06c950..000000000 --- a/settings/add-members.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Editor Permissions' -description: 'Allow more members of your team to update your docs' -icon: 'user-group-simple' ---- - -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. - - - - - -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. - -Learn more about our pricing [here](https://mintlify.com/pricing). diff --git a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx deleted file mode 100644 index c3f7afd6e..000000000 --- a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: 'Choosing a Handshake' -description: 'How to decide which Handshake method is right for your docs' ---- - - - This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake). - - -Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods: - -1. **Password**: Configure a set of global passwords for your documentation site. -2. **JWT**: Use your own login flow to authenticate your users via a JWT in the URL. -3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow. -4. **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required. - -## Prerequisites - - - - - - Your security requirements allow for password sharing between documentation readers. - - - - - You have some existing login flow. - - You can add a final step in this login flow that creates a JWT and redirects to the docs. - - - - - You have an existing OAuth server that supports the Authorization Code flow. - - You can create a new API endpoint that can be accessed by the returned OAuth access token. - - - - - Your documentation readers are also your documentation editors. - - - -## Pros & Cons - - - - Pros: - - - Super simple setup - - No configuration required for adding new users - just share the password - - Cons: - - - Difficult to revoke access to your docs without resetting the password - - Lose personalization features, as there is no way to differentiate users with the same password - - - Pros: - - - Reduced risk of API endpoint abuse - - Zero CORS configuration - - No restrictions on API URLs - - Cons: - - - Must be able to hook into your existing login flow - - - Pros: - - - Heightened security standard - - Cons: - - - Requires significant work if setting up OAuth server for the first time - - Might be overkill for some applications - - - Pros: - - - Zero-config setup - - Cons: - - - Requires all docs readers to have an account in your Mintlify dashboard - - diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx deleted file mode 100644 index d35fd7e3a..000000000 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: 'JWT Handshake' -description: 'Use a customized login flow to authenticate users' ---- - - - 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. - - -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. - -## Implementation - - - - 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. - - - 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 - - - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings. - - - -## 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). - -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. - -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: - - -```ts TypeScript -import * as jose from 'jose'; -import { Request, Response } from 'express'; - -const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; - -const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); - -export async function handleRequest(req: Request, res: Response) { - const user = { - expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration - groups: res.locals.user.groups, - content: { - firstName: res.locals.user.firstName, - lastName: res.locals.user.lastName, - }, - }; - - const jwt = await new jose.SignJWT(user) - .setProtectedHeader({ alg: 'EdDSA' }) - .setExpirationTime('10 s') // 10 second JWT expiration - .sign(signingKey); - - return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); -} -``` - -```python Python -import jwt # pyjwt -import os - -from datetime import datetime, timedelta -from fastapi.responses import RedirectResponse - -private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '') - -@router.get('/auth') -async def return_mintlify_auth_status(current_user): - jwt_token = jwt.encode( - payload={ - 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration - 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration - 'groups': ['admin'] if current_user.is_admin else [], - 'content': { - 'firstName': current_user.first_name, - 'lastName': current_user.last_name, - }, - }, - key=private_key, - algorithm='EdDSA' - ) - - return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302) -``` - diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx deleted file mode 100644 index 9839bdc17..000000000 --- a/settings/authentication-personalization/authentication-setup/mintlify.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Mintlify Auth Handshake" -description: "Use Mintlify to authenticate users" ---- - - - The Mintlify Auth Handshake is available only for Authentication, *not* - Personalization. - - -You can use Mintlify to authenticate and manage access to your documentation. Anyone that can access your dashboard will automatically be able to see your documentation. - -This handshake method also enables private preview deployments, so that only Mintlify authenticated users will be able to access your preview deployments. - - - Authentication is available only by request. Please{" "} - contact sales for access. After we've - enabled access, you can follow the implementation instructions. - - -### Example - -I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs -to be internal, and the people that will be viewing my docs are the same people that -contribute to my docs. - -To set up authentication with Mintlify, I can go to my [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) -and enable Authentication with the Mintlify Auth Handshake. - -I can then ensure that anyone that should be able to read the docs has been added as a user in -my [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members). - -## Implementation - - - - Go to your [Mintlify dashboard - settings](https://dashboard.mintlify.com/products/authentication) and select - the Mintlify Auth Handshake. - - - Ensure that any users that should be able to view your documentation have - been added as users in your [Mintlify dashboard - settings](https://dashboard.mintlify.com/settings/organization/members). - - diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx deleted file mode 100644 index 45206968c..000000000 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 'OAuth 2.0 Handshake' -description: 'Integrate with your OAuth server to enable user login via the Authorization Code flow' ---- - - - This is the documentation for the OAuth **Authentication** Handshake. The steps for setting up the [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) are slightly different. - - -If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience. - -## Implementation - - - - Go to your [Mintlify authentication 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** (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty. - - - Copy the Redirect URL listed in the [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server. - - - If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users. - 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. - - Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL - to your OAuth configuration. - - - -## Example - -I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`. - -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. - -I then go to the Mintlify dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: -- **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. diff --git a/settings/authentication-personalization/authentication-setup/password.mdx b/settings/authentication-personalization/authentication-setup/password.mdx deleted file mode 100644 index c68a0f886..000000000 --- a/settings/authentication-personalization/authentication-setup/password.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Password Handshake" -description: "Use a set of shared passwords to authenticate users" ---- - - - This is the documentation for the Password **Authentication** Handshake. The - Password Handshake is not available for Personalization. - - -If you don't have strict security requirements, or you don't want to manage a -database of documentation readers, you can use a set of shared passwords to -protect your docs. - - - Authentication is available only by request. Please{" "} - contact our sales team for access. - After we've enabled access, you can follow the implementation instructions. - - -## Implementation - - - - Go to your [dashboard - settings](https://dashboard.mintlify.com/products/authentication) and create - a password. - - - Securely share the password with your documentation readers. That's it! - - - -## Example - -I want to set up authentication for my docs hosted at `docs.foo.com`. I don't want -to have to keep track of who can and cannot access the docs. My main use case for -authentication is to prevent competitors from snooping - password sharing is secure -enough for my team. - -To set up authentication with Mintlify, I go to my Mintlify dashboard and add at -least one password. I then share that password, along with the private docs URL, -with potential customers. diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx deleted file mode 100644 index c6be06046..000000000 --- a/settings/authentication-personalization/authentication-vs-personalization.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: 'Auth vs Personalization' -description: 'How to determine which product is best for you' ---- - -Mintlify offers both Authentication and Personalization. For the most part, Authentication is -just Personalization + privacy. However, there are some key differences that are important to -be aware of, from most important to least: - -### Security Guarantees - -Authentication is a fully-fledged private documentation solution. Every aspect of your docs, -including page content, images, search results, and AI chat features, are completely inaccessible to -unauthenticated users. - -Personalization, on the other hand, offers no security guarantees for your documentation content. -All page content, images, search results, and AI chat features can be accessed by the public. Even -if you are using the hidden pages feature of Personalization, a motivated attacker would still -be able to access the content of a hidden page. - -### Handshake Methods - -Due to the difference in security requirements for Authentication and Personalization, different -handshake methods are available for each. Both methods offer a JWT and OAuth Handshake, although -the setup steps are slightly different. - -Authentication offers two additional Handshake methods: - -- **Password Handshake**, which protects your website with a single configurable global password. - -- **Mintlify Auth Handshake**, which will allow users to view your documentation only if they have -access to your dashboard. - -Personalization offers one additional Handshake method: - -- **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint -that returns data for already-authenticated users. diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx deleted file mode 100644 index 81c5b8a7e..000000000 --- a/settings/authentication-personalization/authentication.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Authentication" -description: "Guarantee privacy of your docs by authenticating users" ---- - -Authentication offers full privacy for all of your -documentation content by requiring users to authenticate before viewing any content, such as: - -- Documentation page content -- Images used in documentation pages -- Search results -- AI chat interactions - -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) - -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). diff --git a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx deleted file mode 100644 index 9c7823cc3..000000000 --- a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: 'Choosing a Handshake' -description: 'How to decide which Handshake method is right for your docs' ---- - - - This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication-setup/choosing-a-handshake). - - -Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods: - -1. **Shared Session**: Utilize the same session token used by your dashboard to authenticate users. -2. **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL. -3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the PKCE flow. - -## Prerequisites - - - - - - You have a dashboard or other user portal hosted at your domain. - - Your users' session credentials are stored as cookies. - - You can create a new API endpoint at the same origin or a subdomain of your dashboard. - - If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com` - - If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com` - - Your docs are hosted at the same domain as your dashboard. - - If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` - - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` - - - - - You have some existing login flow. - - You can add a final step in this login flow that creates a JWT and redirects to the docs. - - - - - You have an existing OAuth server that supports the PKCE flow. - - You can create a new API endpoint that can be accessed by the returned OAuth access token. - - - -## Pros & Cons - - - - Pros: - - - Users that are logged into your dashboard are automatically logged into your docs - - Your users' sessions are persistent, meaning you can refresh data without requiring additional login - - Minimal setup required - - Cons: - - - Your docs will make a request to your backend, which may be undesirable - - You must have a dashboard that uses session authentication - - CORS configuration is usually required - - - Pros: - - - Reduced risk of API endpoint abuse - - Zero CORS configuration - - No restrictions on API URLs - - Cons: - - - Must be able to hook into your existing login flow - - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately - - Every time you want to refresh user data, your users must re-login to your docs - - If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs - - If your users' data rarely changes, this shouldn't be a problem - - - Pros: - - - Heightened security standard - - No restrictions on API URLs - - Cons: - - - Requires significant work if setting up OAuth server for the first time - - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately - - Might be overkill for some applications - - diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx deleted file mode 100644 index 3e4fe195a..000000000 --- a/settings/authentication-personalization/personalization-setup/jwt.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: 'JWT Handshake' -description: 'Use a customized login flow to authenticate users' ---- - - - This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different. - - - -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 send user info to your docs via a JWT in the URL. - -## Implementation - - - - 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. - - - 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 your docs, including the JWT as the hash - - - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings. - - - -## 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). - -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#{SIGNED_JWT}`, and redirect the user. - -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: - -```ts -import * as jose from 'jose'; -import { Request, Response } from 'express'; - -const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; - -const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); - -export async function handleRequest(req: Request, res: Response) { - const user = { - expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), - groups: res.locals.user.groups, - content: { - firstName: res.locals.user.firstName, - lastName: res.locals.user.lastName, - }, - }; - - const jwt = await new jose.SignJWT(user) - .setProtectedHeader({ alg: 'EdDSA' }) - .setExpirationTime('10 s') - .sign(signingKey); - - return res.redirect(`https://docs.foo.com#${jwt}`); -} - -``` - -## Preserving Anchors - -Post-login, if you'd like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. - -Example: - -- Original: `https://docs.foo.com/quickstart#step-one` -- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx deleted file mode 100644 index d786a042f..000000000 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 'OAuth 2.0 Handshake' -description: 'Integrate with your OAuth server to enable user login via the 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. - - -If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. - -## Implementation - - - - 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. - - - 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. - - - 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. - - - -## 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`. - -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. - -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: -- **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. diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx deleted file mode 100644 index 5066952c1..000000000 --- a/settings/authentication-personalization/personalization-setup/shared-session.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 'Shared Session Handshake' -description: 'Seamlessly share user sessions between your dashboard and your docs' ---- - - - This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication. - - -This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. - -## Implementation - - - - Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User](../sending-data) format. - - If the API domain does not *exactly match* the docs domain: - - Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`) - - Ensure your API’s `Access-Control-Allow-Credentials` header is `true` - - These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints. - - - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings. - - - -## Examples - -### Dashboard at subdomain, docs at subdomain - -I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`. - -To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. - -I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. - -### Dashboard at subdomain, docs at root - -I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. - -To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. - -I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. - -### Dashboard at root, docs at root - -I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. - -To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. - -I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field. \ No newline at end of file diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx deleted file mode 100644 index 05baef8e8..000000000 --- a/settings/authentication-personalization/personalization.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Personalization" -description: "A list of features unlocked with Personalization" ---- - -Personalization refers to a suite of features that allow you to customize your -documentation experience based on some information about the user. There are -three major features of Personalization: - -- **Customize MDX content** with a user's information, such as their name, plan, or title. - -- **Prefill API keys** in the API Playground for streamlined use. - -- **Selectively show pages** in the navigation based on a user's groups. - -## How to Use - -### Customizing MDX Content - -When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example: - -Hello, {user.name ?? 'reader'}! - -```jsx -Hello, {user.name ?? 'reader'}! -``` - -This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan: - -Personalization is an enterprise feature. { -user.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. -: user.org.plan !== 'enterprise' -? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. -: <>To request this feature for your enterprise org, contact our team. -} - -```jsx -Personalization is an enterprise feature. { - user.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. - : user.org.plan !== 'enterprise' - ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} -``` - - - The information in `user` is only available after a user has logged in. For - logged out users, the value of `user` will be `{}`. To prevent the page from - crashing for logged-out users, always use optional chaining on your `user` - fields, e.g. `{user.org?.plan}` - - -### Prefilling API Keys - -If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. - -### Showing/Hiding Pages - -By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. -When determining which pages to show to the user, Mintlify will check which groups the user belongs to. -If the user is not in any of the groups listed in the page metadata, the page will not be shown. - -```md ---- -title: "Managing Your Users" -description: "Adding and removing users from your organization" -groups: ["admin"] ---- -``` - -Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata: - -| | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User | -| :------------------------------ | :------------------: | :------------------: | :-------------------------: | -| `groups` not in metadata | ✅ | ✅ | ✅ | -| `groups: []` in metadata | ❌ | ❌ | ❌ | -| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | - - - Note that an empty array in the page metadata is interpreted as "No groups - should see this page." - diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx deleted file mode 100644 index e969fa8bc..000000000 --- a/settings/authentication-personalization/sending-data.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 'Sending Data' -description: 'The shape of user data you can use to personalize your docs' ---- - -Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both: - -```tsx -type User = { - expiresAt?: number; - groups?: string[]; - content?: Record; - apiPlaygroundInputs?: { - header?: Record; - query?: Record; - cookie?: Record; - server?: Record; - }; -}; -``` - - - The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted. - For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks. - - - A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown. - - - A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!` - - - User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. - - The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section. - - - \ No newline at end of file diff --git a/settings/authentication.mdx b/settings/authentication.mdx deleted file mode 100644 index 35bb3eddc..000000000 --- a/settings/authentication.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Single Sign-On (SSO)" -description: "Customize how your team can login to your Mintlify dashboard" -icon: 'user-unlock' ---- - -Mintlify supports 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! - - - SSO functionality is available on our Enterprise plan. [Contact - us](https://mintlify.com/enterprise) to learn more! - - -## Okta - - - - - - Under `Applications`, click to create a new app integration using SAML 2.0. - - - Enter the following: - * Single sign-on URL (provided by Mintlify) - * Audience URI (provided by Mintlify) - * Name ID Format: `EmailAddress` - * Attribute Statements: - | Name | Name format | Value - | ---- | ----------- | ----- - | `firstName` | Basic | `user.firstName` | - | `lastName` | Basic | `user.lastName` | - - - Once the application is set up, navigate to the sign-on tab and send us the metadata URL. - We'll enable the connection from our side using this information. - - - - - - - Under `Applications`, click to create a new app integration using OIDC. - You should choose the `Web Application` application type. - - - 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. - - - - - -## Google Workspace - - - - - - 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. - - ![](/images/gsuite-saml-metadata.png) - - - - On the Service provider details page, enter the following: - * ACS URL (provided by Mintlify) - * Entity ID (provided by Mintlify) - * Name ID format: `EMAIL` - * Name ID: `Basic Information > Primary email` - - - ![](/images/gsuite-sp-details.png) - - - On the next page, enter the following attribute statements: - | Google Directory Attribute | App Attribute | - | -------------------------- | ------------- | - | `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! - - - - - diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx deleted file mode 100644 index 7bd9f7e69..000000000 --- a/settings/broken-links.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Redirects and Broken Links" -description: "Tools to help prevent invalid links" -icon: 'link-simple' ---- - -When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title. - -## Broken Links - -Catch broken links with our CLI. Simply [install the CLI](/development) and run the command: - -```bash -mintlify broken-links -``` - -The CLI will identify any relative links in your docs that don't exist. - -## Redirects - -Set up 301 redirects by adding the `redirects` field into your `mint.json` file. - -```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" - } -] -``` - -This will permanently redirect `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. - -To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`. - -```json -"redirects": [ - { - "source": "/beta/:slug*", - "destination": "/v2/:slug*" - } -] -``` diff --git a/settings/custom-domain.mdx b/settings/custom-domain.mdx deleted file mode 100644 index 4fdfecb5f..000000000 --- a/settings/custom-domain.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 'Custom Domain' -description: "Host your documentation at your website's custom domain" -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. - - - Looking to set up a custom subdirectory like mintlify.com/docs? Find - 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`. - - - Custom Domain - Custom Domain - - -## Verification with Vercel - -If Vercel happens to be your domain provider, you will have to add a verification `TXT` record. This information will show on your dashboard after submitting your custom domain, as well as be emailed to you. - -## Configuring your DNS - -1. Proceed to your domain's DNS settings on your domain provider's website. -2. Create a new DNS entry, inputting the following values: - -``` -CNAME | docs | cname.vercel-dns.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. - -Please [contact support](mailto:sales@mintlify.com) if you don't see the custom domain set up after the above configuration. diff --git a/settings/github.mdx b/settings/github.mdx deleted file mode 100644 index 310499c06..000000000 --- a/settings/github.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: GitHub -description: "Sync your docs with a GitHub repo" -icon: 'github' ---- - -Mintlify integrates with the GitHub API, enabling synchronization between your -docs and your GitHub repository. This integration is made possible through the -utilization of -[GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps). - -## Installation - -To begin, you need to install the Mintlify GitHub App into the GitHub account -where your docs repo resides. Installing a GitHub App requires either -organization ownership or admin permissions in a repository. If you lack the -necessary permissions, the repository owner will need to approve the request. -You can access the installation page by logging into the -[Mintlify dashboard](https://dashboard.mintlify.com). - -For GitHub Apps, you can choose to only give permissions to a single repository. -We highly recommend you do so as we only need access to the repository where -your docs are hosted. - - - - - -## Permissions - -During the installation of our GitHub app, you will be prompted to grant certain -permissions: - -- Read and write access to `checks`, `contents`, `deployments`, `pull requests`, - and `workflows` - -These permissions are leveraged to provide a seamless experience when managing -your docs. - -When you make a commit to the branch you configured as your docs deployment -branch, we fetch the contents of the files changed to update your docs. To -accomplish this we need read access to your `contents`. - -When pull requests are created we create a check and preview deployment which is -why we need write access to `checks` and `deployments`. - -Inside the Mintlify web editor, Mintlify works on your behalf to create branches -and pull requests which is why we need write access to `pull requests` and -`workflows`. - - - If you are concerned about the write permissions, the GitHub App will only - have access to the repos you give it access to _and_ if you have branch - protections on it _cannot_ push directly to your branches - it abides by your - branch protection rules. - - -## Repositories Installations - -When installing our GitHub app, you will be prompted to select all repositories -or a subset of them. This selection can be changed at any time by going to the -[GitHub app settings](https://github.com/apps/mintlify/installations/new). diff --git a/settings/gitlab.mdx b/settings/gitlab.mdx deleted file mode 100644 index 01c0b82bf..000000000 --- a/settings/gitlab.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "GitLab" -description: "Sync your docs with a GitLab repo" -icon: "gitlab" ---- - -We use a combination of Access tokens and Webhooks to authenticate and sync -changes between GitLab and Mintlify. - -- We use Access tokens to pull information from GitLab. -- We use Webhooks so GitLab can notify Mintlify when changes are made. - - This allows Mintlify to create preview deployments when a MR is created. - -## Set up the connection - - - - Within your GitLab project, navigate to `Settings` > `General` and find the `Project ID`. - - - - - - a. Navigate to `Settings` > `Access Tokens`. - - b. Select `Add new token`. - 1. Name the token "Mintlify". - 2. If you have a private repo, you must set the role as `Maintainer`. - 3. Choose `api` and `read_api` for the scopes. - - c. Finally click `Create project access token` and copy the token. - - - - - - - - Within the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done. - - - - - - -## Create the webhook - -Webhooks allow us to receive events when changes are made so that we can -automatically trigger deployments. - - - - - - - - - In the "URL" field, enter the endpoint `https://leaves.mintlify.com/gitlab-webhook` and name the webhook "Mintlify". - - - - Paste the Webhook token generated after setting up the connection. - - - - - - Select the events you want to trigger the webhook: - - Push events (All branches) - - Merge requests events - - When you're done it should look like this: - - - - - - After creating the Webhook, click the "Test" dropdown and select "Push events" to send a sample payload to ensure it's configured correctly. It'll say "Hook executed successfully: HTTP 200" if configured correctly. - - This will help you verify that everything is working correctly and that your documentation will sync properly with your GitLab repository. - - - - - - - - - Reach out to the Mintlify team if you need help. Contact us - [here](https://mintlify.com/enterprise). - - -[git-settings]: https://dashboard.mintlify.com/settings/deployment/git-settings diff --git a/settings/global.mdx b/settings/global.mdx deleted file mode 100644 index 350cb3c18..000000000 --- a/settings/global.mdx +++ /dev/null @@ -1,808 +0,0 @@ ---- -title: "Global Settings" -description: "Customize your documentation using the mint.json file" -icon: "wrench" ---- - -Every Mintlify site needs a `mint.json` file with the core configuration -settings. Learn more about the [properties](#properties) or from an -[example](#example-mint-json) - -## Properties - -### Styling - - - Name of your company or project. Used for the global title. - - - - Path to logo image or object with path to "light" and "dark" mode logo images, - and where the logo links to. SVG format is recommended. It does not pixelate - and the file size is generally smaller. - - - - Path to the logo in light mode. For example: `/path/to/logo.svg` - - - - Path to the logo in dark mode. For example: `/path/to/logo.svg` - - - - Where clicking on the logo links you to - - - - - - - Path to the favicon image. For example: `/path/to/favicon.svg` - - - - Hex color codes for your global theme - - - - The primary color. Used most often for highlighted content, section - headers, accents, in light mode - - - - The primary color for dark mode. Used most often for highlighted content, - section headers, accents, in dark mode - - - - The primary color for important buttons - - - - The color of the background in both light and dark mode - - - - The hex color code of the background in light mode - - - - The hex color code of the background in dark mode - - - - - - - - - A preset theme configuration that changes the look and feel of the project. A - theme is a set of default styling configurations. Examples: - [Venus](https://starter-venus.mintlify.app), - [Quill](https://starter-quill.mintlify.app), - [Prism](https://starter-prism.mintlify.app) - - - - The global layout style of the documentation. - - - - Set a decorative background. - - - - The style of the decorative background. - - - - - - Set a custom background image to be displayed behind every page. - - - - Custom fonts. Apply globally or set different fonts for headings and the body - text. - -Example: - -```json -"font": { - "headings": { - "family": "Roboto" - }, - "body": { - "family": "Oswald" - } -} -``` - - - - The font family name. Custom fonts and all [Google - Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans", - "Playfair Display" - - - - The font weight. Precise values such as `560` are also supported for - variable fonts. Check under the Styles section for your Google Font for - the available weights. - - - - The URL to the font file. Can be used to specify a font that is not from - Google Fonts. - - - - The font format. Required if using a custom font source (`url`). - - - - - - - Customize the dark mode toggle. - - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - - - - - Customize the styling of components within the sidebar. - - - - The styling of the navigation item. - - - - - - Styling configurations for the topbar. - - - - The styling of the navigation item. - - - - - - The location options for the search bar. - - - - The location of the search bar. - - - - - - The style of the rounded edges. - - - - The style of the code block. - - - - `auto` will automatically switch between light and dark mode based on the - user's system preferences. - - - - -### Structure - - - An array of groups with all the pages within that group - - - - The name of the group. - - - - The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array. - - - - The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders. - - - - The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin - - - - - - - Array of names and urls of links you want to include in the topbar - - - - The name of the button. - - - - The url once you click on the button. Example: `https://mintlify.com/contact` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided - including the number of GitHub stars. - - - - If type is a link: What the button links to. If type is a github: Link to - the repository to load GitHub information from. - - - - Text inside the button. Only required if type is a link. - - - - The style of the button. - - - - Whether to display the arrow - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - -Versions can be leveraged for localization. You can store translated content -under a version, and once you specify the `locale` any fixed text in Mintlify, -such as 'Was this page helpful?', will automatically be translated based on the -locale. We currently support localization in English, Chinese, Spanish, French, -Japanese, and Portuguese. - - - Localization auto-translates the UI and fixed assets in the docs, such as "Was - this page helpful?". You must translate the content of the pages yourself. - - -For more information, please refer to our -[versioning & localization documentation](/settings/versioning). - -Example: - - - ```json Default - "versions": ["v1.0", "v1.1"] - ``` - - ```json Localization - "versions": [ - { - "name": "English", - "locale": "en", - }, - { - "name": "Español", - "locale": "es" - } - ] - ``` - - - - - - The version name. - - - - The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`. - - - - Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version. - - - - - - - An array of the anchors, includes the icon, color, and url. - -{" "} - - - -{" "} - - - - - - The name of the anchor label. - - Example: `Community` - - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - - Used if you want to hide an anchor until the correct docs version is selected. - - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. Note: if you have - tabs configured, this does not apply. - - - - The name of the top-most anchor - - - - Font Awesome icon. - - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - An array of navigational tabs. - -Example: - -```json -"tabs": [ - { - "name": "Writing Content", - "url": "content" - }, - { - "name": "API References", - "url": "api-playground" - } -] -``` - - - - The name of the tab label. - - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - Pass `true` if you want to hide the tab until you directly link someone to docs inside it. - - - - - - - An object to configure the footer with socials and links. - Example: - -```json -"footer": { - "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" }, - "links": [ - { - "title": "Column 1", - "links": [ - { "label": "Column 1 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 1 Link 2", "url": "https://mintlify.com" } - ] - }, - { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] - } - ] -} -``` - - - - One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter` - - Example: `x` - - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - - Title of the column - - - - The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab. - - - - - - - Configurations to enable feedback buttons - - - - Enables a rating system for users to indicate whether the page has been helpful - - - - Enables a button to allow users to suggest edits via pull requests for public repositories. - - - If your docs repo is private, `suggestEdit` will not work. - - - - - Enables a button to allow users to raise an issue about the documentation - - - - - - - Configurations to change the search prompt - - - - Set the prompt for the search bar. Default is `Search...` - - - - -### API Configurations - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground). - - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground) - - - - By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior. - - Required for select request types, such as file uploads. - - - - - - Configurations for API requests - - - - Configurations for the auto-generated API request examples - - - - An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java` - - - - - - - - Configurations for the param fields in the API Playground - - - - The default expanded state of expandable options in the API playground. - - `"all"` - every expandable component is expanded - - `"topLevel"` - every top-level expandable component is expanded - - `"topLevelOneOfs"` - every top-level `oneOf` type is expanded - - `"none"` - every expandable component is closed (default behavior) - - - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - -Examples: - - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - - ```json Relative - "openapi": "/openapi.json" - ``` - - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - -### Integrations - - - Configurations to add third-party integrations (excluding analytics integrations) - - - - Enables Intercom widget on docs site. The value should be your Intercom App ID. - - - - Enables Frontchat widget on docs site. The value should be your Frontchat App ID. - - - - - - - Configurations to add third-party analytics integrations. See full list of - supported analytics [here](/integrations/analytics/overview). - - -### Redirects - - - An array of paths you want to configure to permanently redirect to another path - -Example: - -```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" - } -] -``` - - - - The path that you want to redirect from. - - Example: `/source` - - - - The path that you want to redirect to. - - Example: `/destination` - - - - - -### Search Engine Optimization - - - Settings for Search Engine Optimization. - -Example: - -```json -"seo": { - "indexHiddenPages": true -} -``` - - - - Enables indexing pages not included in `navigation`. - - - - -## Example `mint.json` - -Click on the following dropdown to view a sample configuration file - - - ```json - { - "name": "Mintlify", - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#16A34A", - "light": "#4ADE80", - "dark": "#166534" - }, - "topbarLinks": [ - { - "name": "Contact Us", - "url": "mailto:support@mintlify.com" - } - ], - "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/start" - }, - "anchors": [ - { - "name": "API Components", - "icon": "rectangle-terminal", - "color": "#f59f0b", - "url": "api-components" - }, - { - "name": "Community", - "icon": "comments", - "color": "#2564eb", - "url": "https://mintlify.com/community" - } - ], - "navigation": [ - { - "group": "Getting Started", - "pages": ["introduction", "quickstart"] - }, - { - "group": "API Components", - "pages": ["api-playground/overview", "api-playground/configuration"] - }, - { - "group": "Settings", - "pages": ["settings/global", "settings/page"] - }, - { - "group": "Analytics", - "pages": ["analytics/posthog"] - } - ], - "footerSocials": { - "github": "https://github.com/mintlify", - "slack": "https://mintlify.com/community", - "x": "https://x.com/mintlify" - }, - "integrations": { - "intercom": "APP_ID", - "frontchat": "CHAT_ID" - } - } - ``` - - -## More Customization - -Learn more about how to further customize your docs with custom CSS and JS in -[Custom Scripts](https://mintlify.com/docs/advanced/custom/). diff --git a/settings/navigation.mdx b/settings/navigation.mdx deleted file mode 100644 index ec1ab6e76..000000000 --- a/settings/navigation.mdx +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: "Navigation" -description: "Organize your docs directory to guide your users to the information they need " -icon: "map" ---- - -## Tabs - -Tabs help distinguish between different topics or sections of your -documentation. They show up above the main sidebar. - - - - - - - -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of -the tab object should map to a folder of content added to your sidebar, or an -external link. - -```json -"tabs": [ - { - "name": "API References", - "url": "api-references" - }, - { - "name": "Content", - "url": "content" - }, - { - "name": "Blog", - "url": "https://your-website.com/blog" - } -] -``` - -To configure the default `Documentation` primary tab, add the `primaryTab` field -to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. - -```json -"primaryTab": { - "name": "Home" -} -``` - -## Anchors - -Anchors provide another way to direct users to sections of your documentation, -or link out to external URLs. - - - - - - - -Configure anchors with the `anchors` field of the `mint.json` file. The `url` -field of the tab object should map an external link, or a folder of content -added to your sidebar. More fields for anchors can be found -[here](/settings/global). - -```json -"anchors": [ - { - "name": "API References", - "icon": "code", - "url": "api-references" - }, - { - "name": "Content", - "icon": "pencil", - "url": "content" - }, - { - "name": "Contact us", - "icon": "envelope", - "url": "https://mintlify.com/contact-us" - } -] -``` - -To configure the default `Documentation` top anchor, add the `topAnchor` field -to your `mint.json`. - -```json -"topAnchor": { - "name": "Home", - "icon": "building" -} -``` - -## Sidebar - -Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) - - - Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. - - -```json Regular Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": ["quickstart"] - } -] -``` - -### Groups - -Create groups by recursively nesting a group within a group. - -```json Nested Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } -] -``` - -### Folders - -Simply put your MDX files in folders and update the paths in `mint.json`. - -For example, to have a page at `https://yoursite.com/your-folder/your-page` you -would make a folder called `your-folder` containing an MDX file called -`your-page.mdx`. - - - You cannot use `api` for the name of a folder unless you nest it inside - another folder. Mintlify uses Next.js which reserves the top-level `api` - folder for internal server calls. We recommend using the folder name - `api-reference` instead. - - - - ```json Navigation With Folder - "navigation": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } - ] - ``` - -```json Nested Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } -] -``` - - - -### Hidden Pages - -MDX files not included in `mint.json` will not show up in the sidebar but are -accessible by linking directly to them. - -Hidden pages are not indexed for search within your docs by default. If you -would like to override this behavior, you can set the -[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute -in your `mint.json` to `true`. - -## Topbar - -### Links - -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. - - - - - -The `topbarLinks` field supports the following fields: `name`, `url`. - -```json - "topbarLinks": [ - { - "name": "Community", - "url": "https://mintlify.com/community" - } - ] -``` - -### CTA Button - -Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton` -field. - - - - - -The `topbarCtaButton` field supports the following fields: `name`, `url`, `type`, `style`, and `arrow`. For more information on the options for these fields, see the [mint.json schema](/settings/global#structure). - -```json - "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/get-started" - } -``` - -#### GitHub - -You can also configure the CTA button to link directly to your GitHub -repository. Use the `topbarCtaButton` field with the `type` set to `github`. - - - - - -```json - "topbarCtaButton": { - "type": "github", - "url": "https://github.com/mintlify/docs" - } -``` diff --git a/settings/preview-deployments.mdx b/settings/preview-deployments.mdx deleted file mode 100644 index b12296dab..000000000 --- a/settings/preview-deployments.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Preview Deployments" -description: "Preview changes to your docs in a live deployment" -icon: "street-view" ---- - - - Preview Deployments are available on the Growth and Enterprise plans. Please{" "} - contact sales for more information. - - -Preview Deployments allow you to preview changes to your docs in a live deployment without merging those changes to your production branch. - -If you have created a pull or merge request when using Git, the generated preview URL will be available as a comment from the Mintlify bot in the PR. This URL will always reflect the latest deployment changes. - -## Sharing Preview Deployments - -After generating a preview URL, you can share that link with anybody for them to view. - -### Authenticated Preview Deployments - -If you'd like to restrict access to your Preview Deployments, you can set up preview deployment authentication. When using this authentication method, only Mintlify authenticated users will be able to access your Preview Deployments. - -To set up preview deployment authentication, please [contact sales](mailto:sales@mintlify.com). diff --git a/settings/seo.mdx b/settings/seo.mdx deleted file mode 100644 index b81352b91..000000000 --- a/settings/seo.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: 'SEO' -description: 'Mintlify automatically generates most meta tags. If you want to customize them, you can set default values in mint.json or change them per page.' -icon: 'magnifying-glass' ---- - - - -- og:site_name -- og:title -- og:description -- og:url -- og:image -- og:locale -- og:logo -- article:publisher -- twitter:title -- twitter:description -- twitter:url -- twitter:image -- twitter:site -- og:image:width -- og:image:height -- robots - - - -## Default meta tags - -You can set default meta tags by adding the `metadata` field to your `mint.json`. - -```json -"metadata": { - "og:image": "link to your default meta tag image" -} -``` - -## Changing meta tags on one page - -Add your meta tags to the page's metadata like so: - -```md ---- -title: 'Your Example Page Title' -'og:image': 'link to your meta tag image' ---- -``` - - - -Meta tags with colons need to be typed with quotes around them when you put them in the page metadata. - - - -## Sitemaps - -Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. Simply add `/sitemap.xml` to the end of your website URL to see your sitemap. We recommend submitting the sitemap to search engines for improved SEO. - -Only pages included in your `mint.json` are included by default. To include hidden links, add `seo.indexHiddenPages` to your `mint.json`: - -```json -"seo": { - "indexHiddenPages": true -} -``` - -## Disabling indexing -If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/page) of your page: -``` ---- -noindex: true ---- -``` - -You can also specify `noindex` for all pages in your docs by setting the `metadata.robots` field to `"noindex"` in your `mint.json`: - -```json -"metadata": { - "robots": "noindex" -} -``` \ No newline at end of file diff --git a/settings/versioning.mdx b/settings/versioning.mdx deleted file mode 100644 index bc60a79b1..000000000 --- a/settings/versioning.mdx +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: "Versioning & Localization" -description: "Build separate versions or localizations" -icon: "square-chevron-down" ---- - -Mintlify supports versioning or localization. You can use one or the other, not both. - -These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized. - -## Versioning - -### Setup - -Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version. - -If you would like to specify a default version, you can do so like this: - -```json -"versions": [ - { - "name": "version-name", - "default": true - } -] -``` - - - The versions dropdown will show your versions in the order you include them in - `mint.json`. - - -### Versioning Groups and Pages - -The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group. - -You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence. - - -```json Groups (mint.json) -"navigation": [ - { - "group": "Getting Started", - "version": "v1", - "pages": [...] - } -], -``` - -```yaml Pages (quickstart.mdx) ---- -title: "Quickstart" -version: "v2" ---- -``` - - - - - While it is possible to nest versioned groups within versioned groups, it is - not recommended. If you do take this approach, the more deeply-nested version - takes precedence. - - -#### Versioning Tabs and Anchors - -You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor. - -In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version. - - -```json Tabs -"tabs": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Migrating from V1 to V2", - "url": "https://mintlify.com/changelog/v2" - }, -], -``` - -```json Anchors -"anchors": [ - { - "name": "API Reference V1", - "url": "v1/api-reference", - "version": "v1" - }, - { - "name": "API Reference V2", - "url": "v2/api-reference", - "version": "v2" - }, - { - "name": "Migrating from V1 to V2", - "url": "https://mintlify.com/changelog/v2", - "version": "v2" - }, -], -``` - - - -#### Sharing Between Versions - -Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content! - - - When using localization with versioning, each version can have its own set of - translations. This means you can have different language versions for - different API versions, giving you full flexibility in managing both versioned - and localized content. - - -### Troubleshooting - -Common errors and how to fix them - - - - You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2". - - We do not recommend nesting versions inside of each other because it's hard to maintain your docs later. - - - - - If you add versions to your docs and the pages disappeared from your - navigation, make sure you spelled the version the same as in your `versions` - array in `mint.json`. - - - -## Localization - -### Setup - -`"versions"` in your `mint.json` can be leveraged to create different language versions by adding a `locale` value to the version. The first localization from the array serves as the default localization. - -We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), and German (`de`). - -```json mint.json example -"versions": [ - { - "name": "English", - "locale": "en", - }, - { - "name": "French", - "locale": "fr", - }, - { - "name": "Spanish", - "locale": "es" - } -] -``` - - - The versions dropdown will show your localizations in the order you include - them in the `mint.json`. - - -Once setup, the rest of localization is handled by the versioning setup described above. diff --git a/web-editor.mdx b/web-editor.mdx deleted file mode 100644 index 0c945d94b..000000000 --- a/web-editor.mdx +++ /dev/null @@ -1,281 +0,0 @@ ---- -title: 'Web Editor' -description: 'Edit your docs directly from the dashboard with live previews.' ---- - -Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. - -The editor includes a few key features to integrate directly into your existing git workflow, -like creating branches, pull requests, commits, and diffs for your current changes. - -It also includes a fully editable experience for changing and adding content directly, -even with custom components. - -If you understand git workflows and our integrations already, you can skip to [here](#editing-content). - -## Git and update workflows - -### Git basics - -While Web Editor means you don't need to go to GitHub or your command line to make -changes, it's still helpful to know the basics of git. - -Git terminology: - -- **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub). - -- **Commit**: A snapshot of changes made to files in the repository. - -- **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version. - -- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. - -### Making updates - -In order to make updates to your docs, we include a few buttons specifically to -integrate with your git workflow. - - - If you haven't done so already, please install the Mintlify GitHub app to your GitHub account. - You can find [documentation here](#1-deploying-your-docs-repository), or you can install - the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) - page of the dashboard. - - - - - In order to make changes to your docs, you might want to change from the main branch - to avoid publishing directly to your main docs site. - - To do this, you can open the branches modal on the top left of the editor. - - - - - - - From here, you can either switch to a different git branch than `main`, or you can - create a new branch by clicking the **"New Branch"** button. - - - - - - - After you create a new branch, you'll automatically be switched, and all changes - you make will be made to this new branch until you change branches again or reload the page. - - By default, when you load the page again, you'll default to the main branch. - - - As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you. - - - - - In order to make a commit, you have two options, both of which appear on the top - right of the editor: - - - - If you're on the main branch of your docs repository, you can push a commit - directly to the repo by clicking the **"Publish"** button. You'll see your changes - reflect in your git branch the next time you run `git pull`. - - - - - - - - - If you're not on the main branch, you can push a commit to your branch by clicking - on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch - up for review, you can click the **"Publish Pull Request"** button. - - - - - - - - - This will create the pull request for you on GitHub using the branch you selected onto - your main branch. - - - - If you do put your pull request up for review, you can edit the title and description - of the PR, but a default Mintlify title will be provided for you if you leave it - empty. - - - - - - - - -## Editing content - -### Slash commands - -The easiest way to add content in the editor is by using **"Slash commands"**, which are -commands you have access to after typing `/` in the **"Visual Editor"** mode: - - - - - - -As you type, you'll see more options pop up: - - - - - - -#### Content blocks - -Here are the types of content blocks available to add in the **"Visual Editor"**: - - - - - Paragraph - Headings - Bullet List - Numbered List - Table - Image - Blockquote - - - - - - Callouts - Accordions - Accordion Group - Cards - Card Group - Code Block - Code Group - Tabs - Steps - Frames - Update - - - - -### Adding images - -You can add images to your page by typing `/image` and either clicking on the **"Image"** -option or hitting ↓ + Enter on the **"Image"** option. - -This will open up the image modal where you have the option to either upload a new -image or use an existing image from the repo. - - - - - - -Uploading an image can be done through the modal: - - - - - - -And you can preview an existing image before you add it. - - - - - - -### Editing images - -In order to edit images, you just have to hover over the image to see the **"Delete"** -and **"Edit"** buttons on the top right of the image. - - - - - - -Clicking the **"Edit"** button lets you edit the attributes of the image. - - - - - - -If you want to update the source of an image to be a new image that you haven't yet -uploaded, you have to first delete the image you're changing, and then add a new one -using the [instructions above](#adding-images). - -## Editor modes - -In order to offer the most flexibility, the editor has three modes: - - - - - - -### Visual Editor - -The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion. -It offers you a view into your docs in a fully editable way that reflects what the final -page would look like on your main docs site. - -### Source Editor - -The **"Source Editor"** offers you a way to edit your MDX files in code, the same way -you'd do in your IDE. This offers less flexibility, in that our components aren't available -for auto-complete, but it does have two unique advantages. - -1. It allows you to edit props of components (see our [limitations below](#current-limitations)) -which is currently not available in **"Visual Editor"** mode yet. - -2. It allows you to correct syntax errors which might've appeared in your repo that -might not be compatible with **"Visual Editor"** mode until you've fixed them. - -### Diff View - -The **"Diff View"** is a way to view the changes made to a specific document before -committing it to your repository. - -This will help you see changes you've made along with formatting changes made by -the editor. - -## Current limitations - -We do have a few current limitations in the editor that we're working to resolve. - - - - You currently cannot live-update your navigation based on added/edited files. You - still have to manually edit renamed, added, and deleted files in your `mint.json` - - - - We currently don't show any previews for custom snippets. This is on our roadmap to support - as fully editable components. - - - - We currently don't show any previews for OpenAPI specs. This is on our roadmap to support - as a read-only preview. - - - -## Feedback - -If you have any bug reports, feature requests, or other general feedback, we'd love to hear -where we can improve. - -Email us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file