diff --git a/ai-native.mdx b/ai-native.mdx new file mode 100644 index 000000000..27f85904c --- /dev/null +++ b/ai-native.mdx @@ -0,0 +1,47 @@ +--- +title: "AI-native" +description: "Learn how AI enhances reading, writing, and discovering your documentation" +--- + +When you host your documentation on Mintlify, built-in AI features help your users find answers and your team maintain content more efficiently. Your content provides the context for these AI-native features to improve the experiences of reading, writing, and discovering your documentation. + +## What makes your documentation AI-native + +### Reading + +In addition to reading individual pages, users can chat with the [assistant](/ai/assistant) in your documentation for immediate answers to their questions and links to relevant content. The assistant helps guide users through your product with accurate information from your documentation. Embed the assistant into custom apps with the [API](api-reference/assistant/create-assistant-message) to extend where users can access your documentation. + +### Writing + +The [agent](/ai/agent) helps you write and maintain documentation. It creates pull requests with proposed changes based on your prompts, pull requests, and Slack threads. Add the agent to your Slack workspace so that anyone on your team can help maintain your documentation by chatting with the agent. Or embed the agent into custom apps via the [API](/api-reference/agent/create-agent-job). + +Configure popular tools like [Cursor](/guides/cursor), [Claude Code](/guides/claude-code), and [Windsurf](/guides/windsurf) to reference the Mintlify schema, your style guide, and best practices. + +### Discovering + +Your site is automatically optimized for AI tools and search engines to help users discover your documentation. All pages are sent as Markdown to AI agents instead of HTML, which helps these tools process your content faster and use fewer tokens. Every page is also available to view as Markdown by appending `.md` to the URL. + +Mintlify hosts `llms.txt` and `llms-full.txt` files for your documentation. These industry-standard files help LLMs index your documentation and respond efficiently with relevant information to user queries. + +Your documentation site also hosts an MCP server that lets users connect your documentation directly to their AI tools for up to date information about your product directly where they want it. + +Full-text search and semantic understanding help users and AI tools find relevant information quickly. Search understands user intent rather than just matching keywords. And if a user encounters a 404 error, your site suggests related pages to help them find what they're looking for. No configuration required. + +## Enable AI features + +Select any of the following cards for more information. + + + + Configure the assistant to search external sites or direct people to your support team if it can't answer their questions. + + + Add the agent to your Slack workspace or embed it into custom apps to have it help write and update your documentation. + + + Add a menu to pages that lets users query AI tools, connect to your MCP server, and copy pages as context with one click. + + + Your site has a hosted MCP server that lets users connect your documentation directly to their AI tools. Make your users aware of your MCP server and how to connect to it. + + diff --git a/ai/agent.mdx b/ai/agent.mdx index 6de2b6309..770aaea85 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -1,7 +1,6 @@ --- title: "Agent" description: "The agent helps you write and maintain documentation" -icon: "pen-line" --- diff --git a/guides/assistant.mdx b/ai/assistant.mdx similarity index 97% rename from guides/assistant.mdx rename to ai/assistant.mdx index 8c7c4bbe6..e5ea70b54 100644 --- a/guides/assistant.mdx +++ b/ai/assistant.mdx @@ -1,7 +1,6 @@ --- title: "Assistant" description: "Help users succeed with your product and find answers faster" -icon: "bot" --- @@ -114,7 +113,7 @@ Structure your documentation to help the assistant provide accurate, relevant an - Provide sufficient conceptual content about features and procedures. - Include examples and use cases. - Cross-reference related topics. - - Add [hidden pages](/guides/hidden-pages) with additional context that users don't need, but the assistant can reference. + - Add [hidden pages](/organize/hidden-pages) with additional context that users don't need, but the assistant can reference. ## Exporting and analyzing queries diff --git a/ai/contextual-menu.mdx b/ai/contextual-menu.mdx index f7621bbb6..9b0af219f 100644 --- a/ai/contextual-menu.mdx +++ b/ai/contextual-menu.mdx @@ -1,7 +1,6 @@ --- title: "Contextual menu" description: "Add one-click AI integrations to your docs" -icon: "square-menu" --- import { PreviewButton } from "/snippets/previewbutton.jsx" diff --git a/ai/llmstxt.mdx b/ai/llmstxt.mdx index ed4363e44..89e99b96c 100644 --- a/ai/llmstxt.mdx +++ b/ai/llmstxt.mdx @@ -1,7 +1,6 @@ --- title: "llms.txt" description: "Make your content easier for LLMs to read and index" -icon: "file-code" --- import { PreviewButton } from "/snippets/previewbutton.jsx" diff --git a/ai/markdown-export.mdx b/ai/markdown-export.mdx index 61a63859f..344c8d31a 100644 --- a/ai/markdown-export.mdx +++ b/ai/markdown-export.mdx @@ -1,7 +1,6 @@ --- title: "Markdown export" description: "Quickly get Markdown versions of pages" -icon: "file-text" --- import { PreviewButton } from "/snippets/previewbutton.jsx" diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index a359b62fa..d32f0a993 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -1,7 +1,6 @@ --- title: "Model Context Protocol" description: "Let users access your docs and APIs through their favorite AI tools" -icon: "audio-waveform" keywords: ["mcp"] --- diff --git a/ai/slack-app.mdx b/ai/slack-app.mdx index b63a860e9..16818a12f 100644 --- a/ai/slack-app.mdx +++ b/ai/slack-app.mdx @@ -1,7 +1,6 @@ --- title: "Slack app" description: "Add a bot that searches your docs to answer questions in your Slack workspace" -icon: "slack" --- diff --git a/api-playground/customization/adding-sdk-examples.mdx b/api-playground/adding-sdk-examples.mdx similarity index 100% rename from api-playground/customization/adding-sdk-examples.mdx rename to api-playground/adding-sdk-examples.mdx diff --git a/api-playground/customization/complex-data-types.mdx b/api-playground/complex-data-types.mdx similarity index 100% rename from api-playground/customization/complex-data-types.mdx rename to api-playground/complex-data-types.mdx diff --git a/api-playground/customization/managing-page-visibility.mdx b/api-playground/managing-page-visibility.mdx similarity index 100% rename from api-playground/customization/managing-page-visibility.mdx rename to api-playground/managing-page-visibility.mdx diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index c7eb6a46d..c42f774af 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -33,7 +33,7 @@ To generate pages for API endpoints using `MDX`, configure your API settings in } ``` - Find a full list of API configurations in [Settings](/settings#api-configurations). + Find a full list of API configurations in [Settings](/organize/settings#api-configurations). @@ -76,7 +76,7 @@ To generate pages for API endpoints using `MDX`, configure your API settings in - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs in [Navigation](/navigation). + Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs in [Navigation](/organize/navigation). diff --git a/api-playground/customization/multiple-responses.mdx b/api-playground/multiple-responses.mdx similarity index 100% rename from api-playground/customization/multiple-responses.mdx rename to api-playground/multiple-responses.mdx diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index f9235eef2..75693c08d 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -1,7 +1,6 @@ --- title: "OpenAPI setup" description: "Reference OpenAPI endpoints in your docs pages" -icon: "file-json" --- OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date. @@ -272,7 +271,7 @@ Generated endpoint pages have these default metadata values: To exclude specific endpoints from your auto-generated API pages, add the - [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) + [x-hidden](/api-playground/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec. diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index aa0ada383..5480a8f4b 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,7 +1,6 @@ --- title: "Playground" description: "Enable users to interact with your API" -icon: "play" --- ## Overview diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index e66147844..0b05a0ec2 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -1,7 +1,6 @@ --- title: "Troubleshooting" description: "Common issues with API References" -icon: "message-square-warning" --- If your API pages aren't displaying correctly, check these common configuration issues: @@ -69,7 +68,7 @@ If your API pages aren't displaying correctly, check these common configuration requests, then all of these requests will fail. To fix this, configure your reverse proxy to allow `POST` requests to the `/_mintlify/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.proxy` setting in the `docs.json`, as described in the [settings documentation](/settings#param-proxy). When using this configuration, you will need to configure CORS on your server since requests will come directly from users' browsers rather than through your proxy. + 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.proxy` setting in the `docs.json`, as described in the [settings documentation](/organize/settings#param-proxy). When using this configuration, you will need to configure CORS on your server since requests will come directly from users' browsers rather than through your proxy. If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues: diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index f51ec9831..1f5e5af7e 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,7 +1,6 @@ --- title: "Introduction" description: "Trigger updates, embed AI assistant, and more" -icon: "book-open" --- The Mintlify REST API enables you to programmatically interact with your documentation, trigger updates, and embed AI-powered chat experiences. diff --git a/authentication-personalization/overview.mdx b/authentication-personalization/overview.mdx index 296730c14..1c2e03eaf 100644 --- a/authentication-personalization/overview.mdx +++ b/authentication-personalization/overview.mdx @@ -1,7 +1,6 @@ --- title: "Overview" description: "Control who sees your documentation and customize their experience" -icon: "badge-info" keywords: ["auth"] --- @@ -60,4 +59,4 @@ Choose the method that best fits your existing infrastructure and security requi ## Content customization -All three approaches support content personalization features including dynamic MDX content, API key prefilling, and page visibility controls. For detailed implementation guidance, see [Personalization setup](/authentication-personalization/personalization-setup). +All three approaches support content personalization features including dynamic MDX content, API key prefilling, and page visibility controls. For detailed implementation guidance, see [Personalization setup](/deploy/personalization-setup). diff --git a/changelog.mdx b/changelog.mdx index 95908f490..e0b08715b 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -200,7 +200,7 @@ noindex: true - Support for custom classnames in `h{1-4}` tags for applying custom heading styles - Fixed `h{1-4}` tags rendering as `Heading` components with chips in custom page mode -- Added CSS selectors to [breadcrumbs](/navigation#breadcrumbs) for custom CSS targeting +- Added CSS selectors to [breadcrumbs](/organize/navigation#breadcrumbs) for custom CSS targeting - Fixed stretched open-graph images by analyzing dimensions to maintain proportions at 56px height - Corrected `VSCode` to `VS Code` in contextual menu when enabled - Fixed headings within custom components appearing in table of contents alongside semantic headings @@ -327,13 +327,13 @@ noindex: true - Copy shortcut for code examples generated by assistant - "Ask AI" shortcut on code blocks in documentation to generate explanations from the assistant - Learn more in the [assistant docs](/guides/assistant). + Learn more in the [assistant docs](/ai/assistant). ## Subscribable changelogs - Automatically generate an RSS feed from changelog pages - Integrate RSS-enabled updates with Slack, email, and other tools - Learn more in our new [Changelog guide](/guides/changelogs) + Learn more in our new [Changelog guide](/create/changelogs) @@ -515,7 +515,7 @@ noindex: true ## GitLab Integration Upgrade - We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started. + We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/deploy/gitlab) to get started. ## Web Editor diff --git a/components/accordions.mdx b/components/accordions.mdx index 7aa0c4c8d..8e541b847 100644 --- a/components/accordions.mdx +++ b/components/accordions.mdx @@ -1,7 +1,6 @@ --- title: "Accordions" description: "Collapsible components to show and hide content" -icon: "chevron-down" --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/banner.mdx b/components/banner.mdx index 951a63ace..83267f3cf 100644 --- a/components/banner.mdx +++ b/components/banner.mdx @@ -1,7 +1,6 @@ --- title: "Banner" description: "Add a banner to display important site-wide announcements and notifications" -icon: "layout-panel-top" --- Use banners to display important announcements, updates, or notifications across your entire documentation site. Banners appear at the top of every page, support Markdown formatting, and can be made dismissible. diff --git a/components/callouts.mdx b/components/callouts.mdx index af34a3283..f2fdcea0e 100644 --- a/components/callouts.mdx +++ b/components/callouts.mdx @@ -1,7 +1,6 @@ --- title: 'Callouts' description: 'Use callouts to add eye-catching context to your content' -icon: 'info' --- Callouts can be styled as a Note, Warning, Info, Tip, Check, Danger, or create your own callout: diff --git a/components/cards.mdx b/components/cards.mdx index db1151f79..88297a572 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -1,7 +1,6 @@ --- title: "Cards" description: "Highlight main points or links with customizable layouts and icons" -icon: "square-mouse-pointer" --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/code-groups.mdx b/components/code-groups.mdx index f8574ecbc..58bb8f904 100644 --- a/components/code-groups.mdx +++ b/components/code-groups.mdx @@ -1,7 +1,6 @@ --- title: "Code groups" description: "Display multiple code examples in one component" -icon: "group" --- Use the `CodeGroup` component to display multiple code blocks in a tabbed interface, allowing users to compare implementations across different programming languages or see alternative approaches for the same task. @@ -26,7 +25,7 @@ class HelloWorld { -Code groups inherit global styling from your `docs.json` file. Customize your theme using `styling.codeblocks`. See [Settings](/settings#styling) for configuration options. +Code groups inherit global styling from your `docs.json` file. Customize your theme using `styling.codeblocks`. See [Settings](/organize/settings#styling) for configuration options. ## Creating code groups diff --git a/components/columns.mdx b/components/columns.mdx index 0752c38a4..839528631 100644 --- a/components/columns.mdx +++ b/components/columns.mdx @@ -1,7 +1,6 @@ --- title: 'Columns' description: 'Show cards side by side in a grid format' -icon: 'columns-2' keywords: ['card groups'] --- diff --git a/components/examples.mdx b/components/examples.mdx index e0481c515..fd2a4aab4 100644 --- a/components/examples.mdx +++ b/components/examples.mdx @@ -1,7 +1,6 @@ --- title: "Examples" description: "Display code blocks in the right sidebar on desktop devices" -icon: 'between-horizontal-start' --- The `` and `` components display code blocks in the right sidebar to create a two-column layout that keeps examples visible while users scroll through your content. These components are designed for API documentation, but they work on all pages. diff --git a/components/expandables.mdx b/components/expandables.mdx index 45f8a91e6..583ad5608 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -1,7 +1,6 @@ --- title: "Expandables" description: "Toggle to display nested properties" -icon: "list-tree" --- Use expandables to show and hide nested content within response fields. Expandables are particularly useful for displaying complex object properties in API documentation. diff --git a/components/fields.mdx b/components/fields.mdx index ac86c323f..32fdb435d 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -1,7 +1,6 @@ --- title: "Fields" description: "Set parameters for your API or SDK references" -icon: "letter-text" --- Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields. diff --git a/components/frames.mdx b/components/frames.mdx index 3ff1c4438..0b5efec11 100644 --- a/components/frames.mdx +++ b/components/frames.mdx @@ -1,7 +1,6 @@ --- title: "Frames" description: "Wrap images or other components in a container" -icon: "frame" --- Use frames to display images, diagrams, or other visual content with consistent styling and optional captions. Frames center content and provide visual separation from surrounding text. diff --git a/components/icons.mdx b/components/icons.mdx index 58c234a5b..709e510a1 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -1,7 +1,6 @@ --- title: "Icons" description: "Use icons from popular icon libraries" -icon: "flag" --- import IconsRequired from "/snippets/icons-required.mdx"; diff --git a/components/mermaid-diagrams.mdx b/components/mermaid-diagrams.mdx index bca2c8440..5fdc9a41d 100644 --- a/components/mermaid-diagrams.mdx +++ b/components/mermaid-diagrams.mdx @@ -1,7 +1,6 @@ --- title: "Mermaid" description: "Display diagrams using Mermaid" -icon: "waypoints" --- [Mermaid](https://mermaid.js.org/) lets you build flowcharts, sequence diagrams, Gantt charts, and other diagrams using text and code. diff --git a/components/panel.mdx b/components/panel.mdx index 6a9febc55..4ecace39e 100644 --- a/components/panel.mdx +++ b/components/panel.mdx @@ -1,7 +1,6 @@ --- title: 'Panel' description: 'Specify the content of the right side panel' -icon: 'panel-right' --- You can use the `` component to customize the right side panel of a page with any components that you want. diff --git a/components/steps.mdx b/components/steps.mdx index 3f5b1ba1e..5961c516e 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -1,7 +1,6 @@ --- title: "Steps" description: "Sequence content using the Steps component" -icon: "list-todo" --- import IconsOptional from "/snippets/icons-optional.mdx"; diff --git a/components/tabs.mdx b/components/tabs.mdx index 7aa270a1e..5786a8143 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -1,7 +1,6 @@ --- title: "Tabs" description: "Toggle content using the Tabs component" -icon: "panel-top" --- Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. diff --git a/components/tooltips.mdx b/components/tooltips.mdx index c48fb94b7..24759984c 100644 --- a/components/tooltips.mdx +++ b/components/tooltips.mdx @@ -1,7 +1,6 @@ --- title: "Tooltips" description: "Show a definition when you hover over text" -icon: "message-square" --- Use tooltips to provide additional context or definitions when a user hovers over a string of text. Tooltips can include optional call-to-action links. diff --git a/components/update.mdx b/components/update.mdx index 6e13f200c..b5583e848 100644 --- a/components/update.mdx +++ b/components/update.mdx @@ -1,7 +1,6 @@ --- title: "Update" description: "Keep track of changes and updates" -icon: "list-collapse" --- Use the `Update` component to display changelog entries, version updates, and release notes with consistent formatting. @@ -33,7 +32,7 @@ Use the `Update` component to display changelog entries, version updates, and re ``` -Use multiple `Update` components to create [changelogs](/guides/changelogs). +Use multiple `Update` components to create [changelogs](/create/changelogs). ## Props diff --git a/contact-support.mdx b/contact-support.mdx index 899e7a6cd..b31b482dd 100644 --- a/contact-support.mdx +++ b/contact-support.mdx @@ -1,6 +1,5 @@ --- title: "Contact support" -icon: "circle-help" description: "We're here to help you get the most out of Mintlify" --- diff --git a/settings/broken-links.mdx b/create/broken-links.mdx similarity index 98% rename from settings/broken-links.mdx rename to create/broken-links.mdx index 13bda8396..d26652ce7 100644 --- a/settings/broken-links.mdx +++ b/create/broken-links.mdx @@ -1,7 +1,6 @@ --- title: "Redirects and broken links" description: "Tools to help prevent invalid links" -icon: "link-2" --- When you change the path of a file in your docs folder, it also changes the URL path to that page. This may happen when restructuring your docs or changing the sidebar title. diff --git a/guides/changelogs.mdx b/create/changelogs.mdx similarity index 99% rename from guides/changelogs.mdx rename to create/changelogs.mdx index 3b475121d..be632aa69 100644 --- a/guides/changelogs.mdx +++ b/create/changelogs.mdx @@ -1,7 +1,6 @@ --- title: "Changelogs" description: "Post product updates in your docs with a subscribable RSS feed" -icon: "newspaper" --- Create a changelog for your docs by adding [Update components](/components/update) to a page. @@ -95,7 +94,7 @@ Add `tags` to your `Update` components to replace the table of contents with tag - The table of contents and changelog filters are hidden when using `custom`, `center`, or `wide` page modes. Learn more about [page modes](/pages#page-mode). + The table of contents and changelog filters are hidden when using `custom`, `center`, or `wide` page modes. Learn more about [page modes](/organize/pages#page-mode). ### Subscribable changelogs diff --git a/code.mdx b/create/code.mdx similarity index 98% rename from code.mdx rename to create/code.mdx index 023352229..b054c95a2 100644 --- a/code.mdx +++ b/create/code.mdx @@ -1,7 +1,6 @@ --- -title: "Code" +title: "Format code" description: "Display inline code and code blocks" -icon: "code" --- ## Adding code samples @@ -63,7 +62,7 @@ Enable syntax highlighting by specifying the programming language after the open We use [Shiki](https://shiki.style/) for syntax highlighting and support all available languages. See the full list of [languages](https://shiki.style/languages) in Shiki's documentation. -Customize code block themes globally using `styling.codeblocks` in your `docs.json` file. Set simple themes like `system` or `dark`, or configure custom [Shiki themes](https://shiki.style/themes) for light and dark modes. See [Settings](/settings#styling) for configuration options. +Customize code block themes globally using `styling.codeblocks` in your `docs.json` file. Set simple themes like `system` or `dark`, or configure custom [Shiki themes](https://shiki.style/themes) for light and dark modes. See [Settings](/organize/settings#styling) for configuration options. diff --git a/components/files.mdx b/create/files.mdx similarity index 99% rename from components/files.mdx rename to create/files.mdx index 4ec2107e7..bde1d82a5 100644 --- a/components/files.mdx +++ b/create/files.mdx @@ -1,7 +1,6 @@ --- title: "Files" description: "Serve static assets from your documentation" -icon: "folder" --- Mintlify automatically serves static assets from your documentation repository at the appropriate path on your domain. For example, if you have `/images/my-logo.png` in your repo, the image file is available at `https://docs.your-project.com/images/my-logo.png`. diff --git a/image-embeds.mdx b/create/image-embeds.mdx similarity index 99% rename from image-embeds.mdx rename to create/image-embeds.mdx index 86b78b2da..78bf23dde 100644 --- a/image-embeds.mdx +++ b/create/image-embeds.mdx @@ -1,7 +1,6 @@ --- title: "Images and embeds" description: "Add images, videos, and iframes" -icon: "image" --- Add images, embed videos, and include interactive content with iframes to your documentation. diff --git a/list-table.mdx b/create/list-table.mdx similarity index 99% rename from list-table.mdx rename to create/list-table.mdx index 7d509da16..ccc497c9a 100644 --- a/list-table.mdx +++ b/create/list-table.mdx @@ -1,7 +1,6 @@ --- title: "Lists and tables" description: "Display information in lists and tables" -icon: "list" --- ## Lists diff --git a/reusable-snippets.mdx b/create/reusable-snippets.mdx similarity index 97% rename from reusable-snippets.mdx rename to create/reusable-snippets.mdx index fc17d584b..233bd064c 100644 --- a/reusable-snippets.mdx +++ b/create/reusable-snippets.mdx @@ -1,7 +1,6 @@ --- 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 @@ -98,7 +97,7 @@ Hello, my name is {myName} and I like {myObject.fruit}. ### JSX snippets -1. Export a JSX component from your snippet file. (See [React components](/react-components) for more information): +1. Export a JSX component from your snippet file. (See [React components](/customize/react-components) for more information): ```js icon=square-js snippets/my-jsx-snippet.jsx export const MyJSXSnippet = () => { diff --git a/text.mdx b/create/text.mdx similarity index 99% rename from text.mdx rename to create/text.mdx index f7f02f8ab..3bf9747c0 100644 --- a/text.mdx +++ b/create/text.mdx @@ -1,7 +1,6 @@ --- -title: "Headers and text" +title: "Format text" description: "Learn how to format text, create headers, and style content" -icon: "heading" --- ## Headers diff --git a/settings/custom-404-page.mdx b/customize/custom-404-page.mdx similarity index 98% rename from settings/custom-404-page.mdx rename to customize/custom-404-page.mdx index 916028a51..a25d7f412 100644 --- a/settings/custom-404-page.mdx +++ b/customize/custom-404-page.mdx @@ -1,7 +1,6 @@ --- title: "Custom 404 page" description: "Customize the title and description of your 404 error page" -icon: "file-warning" --- You can control the title and description of the 404 error page that appears when users navigate to broken or missing links. diff --git a/settings/custom-domain.mdx b/customize/custom-domain.mdx similarity index 95% rename from settings/custom-domain.mdx rename to customize/custom-domain.mdx index a023398ee..a0e5c2f8f 100644 --- a/settings/custom-domain.mdx +++ b/customize/custom-domain.mdx @@ -1,13 +1,12 @@ --- 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`? See the [custom subdirectory](/advanced/subpath/cloudflare) docs. + Looking to set up a custom subdirectory like `mintlify.com/docs`? See the [custom subdirectory](/deploy/cloudflare) docs. ## Dashboard settings diff --git a/settings/custom-scripts.mdx b/customize/custom-scripts.mdx similarity index 99% rename from settings/custom-scripts.mdx rename to customize/custom-scripts.mdx index 98dc02e76..36a12e84b 100644 --- a/settings/custom-scripts.mdx +++ b/customize/custom-scripts.mdx @@ -1,7 +1,6 @@ --- title: "Custom scripts" description: "Fully customize your documentation with custom CSS and JS" -icon: "code" --- Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation. diff --git a/react-components.mdx b/customize/react-components.mdx similarity index 98% rename from react-components.mdx rename to customize/react-components.mdx index 4145ef7ea..7ca021b51 100644 --- a/react-components.mdx +++ b/customize/react-components.mdx @@ -1,7 +1,6 @@ --- title: "React" description: "Build interactive and reusable elements with React components" -icon: "react" --- import { ColorGenerator } from "/snippets/color-generator.jsx"; @@ -92,7 +91,7 @@ The counter renders as an interactive React component. ## Importing components -You can import components from your `snippets` folder. Unlike regular React, you cannot import components from every `MDX` file. Reusable components must be referenced from files within the `snippets` folder. Learn more about [reusable snippets](/reusable-snippets). +You can import components from your `snippets` folder. Unlike regular React, you cannot import components from every `MDX` file. Reusable components must be referenced from files within the `snippets` folder. Learn more about [reusable snippets](/create/reusable-snippets). ### Example diff --git a/themes.mdx b/customize/themes.mdx similarity index 99% rename from themes.mdx rename to customize/themes.mdx index 2b93433e4..3e8eb5083 100644 --- a/themes.mdx +++ b/customize/themes.mdx @@ -1,7 +1,6 @@ --- title: "Themes" description: "Customize the appearance of your documentation" -icon: "paint-bucket" mode: "custom" --- diff --git a/advanced/dashboard/permissions.mdx b/dashboard/permissions.mdx similarity index 100% rename from advanced/dashboard/permissions.mdx rename to dashboard/permissions.mdx diff --git a/advanced/dashboard/roles.mdx b/dashboard/roles.mdx similarity index 100% rename from advanced/dashboard/roles.mdx rename to dashboard/roles.mdx diff --git a/advanced/dashboard/sso.mdx b/dashboard/sso.mdx similarity index 100% rename from advanced/dashboard/sso.mdx rename to dashboard/sso.mdx diff --git a/authentication-personalization/authentication-setup.mdx b/deploy/authentication-setup.mdx similarity index 97% rename from authentication-personalization/authentication-setup.mdx rename to deploy/authentication-setup.mdx index 8693e5e40..04fbae74c 100644 --- a/authentication-personalization/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -1,7 +1,6 @@ --- title: "Authentication setup" description: "Control the privacy of your docs by authenticating users" -icon: "file-lock" keywords: ['auth'] --- @@ -116,7 +115,7 @@ Your documentation is hosted at `docs.foo.com` and your team uses the dashboard To enable personalization features, create an API endpoint that: * Accepts OAuth access tokens for authentication. - * Returns user data in the `User` format. See [User data format](/authentication-personalization/personalization-setup#user-data-format) for more information. + * Returns user data in the `User` format. See [User data format](/deploy/personalization-setup#user-data-format) for more information. Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). @@ -168,7 +167,7 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se Modify your existing login flow to include these steps after user authentication: - * Create a JWT containing the authenticated user's info in the `User` format. See [User data format](/authentication-personalization/personalization-setup#user-data-format) for more information. + * Create a JWT containing the authenticated user's info in the `User` format. See [User data format](/deploy/personalization-setup#user-data-format) for more information. * Sign the JWT with your 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. diff --git a/settings/ci.mdx b/deploy/ci.mdx similarity index 96% rename from settings/ci.mdx rename to deploy/ci.mdx index 63710e6a1..e28a1e989 100644 --- a/settings/ci.mdx +++ b/deploy/ci.mdx @@ -1,7 +1,6 @@ --- title: "CI checks" description: "Add checks for broken links, linting, and grammar to the updating process" -icon: "circle-check" --- @@ -12,7 +11,7 @@ Use CI checks to lint your docs for errors and provide warnings before you deplo ## Installation -To begin, follow the steps on the [GitHub](/settings/github) page. +To begin, follow the steps on the [GitHub](/deploy/github) page. For GitHub Apps, you can choose to give permissions to only a single repository. We highly recommend you do so as we only need access to the repository where your docs are hosted. @@ -29,7 +28,7 @@ When enabling checks, you can choose to run them at a `Warning` or `Blocking` le ### Broken links -Similar to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. +Similar to how the [CLI link checker](/create/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. To see the results of this check, visit GitHub's check results page for a specific commit. diff --git a/advanced/subpath/cloudflare.mdx b/deploy/cloudflare.mdx similarity index 100% rename from advanced/subpath/cloudflare.mdx rename to deploy/cloudflare.mdx diff --git a/guides/csp-configuration.mdx b/deploy/csp-configuration.mdx similarity index 100% rename from guides/csp-configuration.mdx rename to deploy/csp-configuration.mdx diff --git a/guides/deployments.mdx b/deploy/deployments.mdx similarity index 94% rename from guides/deployments.mdx rename to deploy/deployments.mdx index cf382d724..54720f072 100644 --- a/guides/deployments.mdx +++ b/deploy/deployments.mdx @@ -1,12 +1,11 @@ --- title: "Deployments" description: "Troubleshoot your deployments" -icon: "boxes" --- Your documentation site automatically deploys when you push changes to your connected repository. This requires the Mintlify GitHub app to be properly installed and connected. -If your latest changes are not appearing on your live site, first check that the GitHub app is installed on the account or organization that owns your docs repository. See [GitHub troubleshooting](/settings/github#troubleshooting) for more information. +If your latest changes are not appearing on your live site, first check that the GitHub app is installed on the account or organization that owns your docs repository. See [GitHub troubleshooting](/deploy/github#troubleshooting) for more information. If the GitHub app is connected, but changes are still not deploying, you can manually trigger a rebuild from your dashboard. diff --git a/settings/github.mdx b/deploy/github.mdx similarity index 99% rename from settings/github.mdx rename to deploy/github.mdx index 74dae45ef..6d258173c 100644 --- a/settings/github.mdx +++ b/deploy/github.mdx @@ -1,7 +1,6 @@ --- title: "GitHub" description: "Sync your docs with a GitHub repo" -icon: "github" --- Mintlify uses a GitHub App to automatically sync your documentation with your GitHub repository. diff --git a/settings/gitlab.mdx b/deploy/gitlab.mdx similarity index 99% rename from settings/gitlab.mdx rename to deploy/gitlab.mdx index e3144f9df..734c47ec1 100644 --- a/settings/gitlab.mdx +++ b/deploy/gitlab.mdx @@ -1,7 +1,6 @@ --- title: "GitLab" description: "Sync your docs with a GitLab repo" -icon: "gitlab" --- We use access tokens and webhooks to authenticate and sync changes between GitLab and Mintlify. diff --git a/guides/monorepo.mdx b/deploy/monorepo.mdx similarity index 98% rename from guides/monorepo.mdx rename to deploy/monorepo.mdx index e94790d60..4aba411f3 100644 --- a/guides/monorepo.mdx +++ b/deploy/monorepo.mdx @@ -1,7 +1,6 @@ --- title: "Monorepo setup" description: "Deploy your docs from a repo that contains multiple projects" -icon: "folder-git" --- Configure Mintlify to deploy documentation from a specific directory within a monorepo. This setup allows you to maintain documentation alongside your code in repositories that contain multiple projects or services. diff --git a/authentication-personalization/personalization-setup.mdx b/deploy/personalization-setup.mdx similarity index 99% rename from authentication-personalization/personalization-setup.mdx rename to deploy/personalization-setup.mdx index af9fcfbcc..71826190f 100644 --- a/authentication-personalization/personalization-setup.mdx +++ b/deploy/personalization-setup.mdx @@ -1,7 +1,6 @@ --- title: "Personalization setup" description: "Let users log in for customized documentation experiences" -icon: "user-cog" --- Personalization customizes your documentation for each user when they are logged in. For example, you can prefill their API keys, show content specific to their plan or role, or hide sections they don't need access to. diff --git a/settings/preview-deployments.mdx b/deploy/preview-deployments.mdx similarity index 95% rename from settings/preview-deployments.mdx rename to deploy/preview-deployments.mdx index d1697c710..0f59e3309 100644 --- a/settings/preview-deployments.mdx +++ b/deploy/preview-deployments.mdx @@ -1,7 +1,6 @@ --- title: "Preview deployments" description: "Preview changes to your docs in a live deployment" -icon: "scan-eye" --- @@ -51,4 +50,4 @@ Preview deployments can be publicly accessible or restricted to authenticated us **Public access**: Preview URLs are publicly viewable by default. Share a preview link with anyone who needs to review your changes. -**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See [Authentication Setup](/authentication-personalization/authentication-setup) for more information. +**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See [Authentication Setup](/deploy/authentication-setup) for more information. diff --git a/guides/reverse-proxy.mdx b/deploy/reverse-proxy.mdx similarity index 100% rename from guides/reverse-proxy.mdx rename to deploy/reverse-proxy.mdx diff --git a/advanced/subpath/route53-cloudfront.mdx b/deploy/route53-cloudfront.mdx similarity index 100% rename from advanced/subpath/route53-cloudfront.mdx rename to deploy/route53-cloudfront.mdx diff --git a/advanced/subpath/vercel.mdx b/deploy/vercel.mdx similarity index 100% rename from advanced/subpath/vercel.mdx rename to deploy/vercel.mdx diff --git a/docs.json b/docs.json index 8dae57e80..e490e772b 100644 --- a/docs.json +++ b/docs.json @@ -19,226 +19,253 @@ "tab": "Documentation", "groups": [ { - "group": "Getting started", + "group": "Get started", + "icon": "rocket", "pages": [ "index", "quickstart", "installation", { - "group": "Web editor", - "icon": "mouse-pointer-2", + "group": "Visual editor", "pages": [ "editor/getting-started", - "editor/git-concepts", - "editor/branches", "editor/content-management", "editor/publishing", "editor/keyboard-shortcuts", "editor/troubleshooting" ] - } + }, + "ai-native", + "migration" ] }, { - "group": "Core configuration", + "group": "Organize", + "icon": "map", "pages": [ - "settings", - "pages", - "navigation", - "themes", - "settings/custom-domain" + "organize/settings", + "organize/navigation", + "organize/pages", + "organize/hidden-pages" ] }, { - "group": "AI optimization", + "group": "Customize", + "icon": "paint-bucket", "pages": [ - "guides/assistant", - "ai/agent", - "ai/llmstxt", - "ai/contextual-menu", - "ai/model-context-protocol", - "ai/markdown-export", - "guides/geo", - "guides/claude-code", - "guides/cursor", - "guides/windsurf" + "customize/custom-domain", + "customize/themes", + "customize/custom-scripts", + "customize/react-components", + { + "group": "Dashboard access", + "pages": [ + "dashboard/sso", + "dashboard/permissions", + "dashboard/roles" + ] + }, + "customize/custom-404-page" ] }, { - "group": "Components", + "group": "Create content", + "icon": "pen-line", "pages": [ - "text", - "image-embeds", - "components/files", - "list-table", - "code", - "reusable-snippets", - "components/accordions", - "components/callouts", - "components/cards", - "components/columns", - "components/code-groups", - "components/examples", - "components/expandables", - "components/fields", - "components/frames", - "components/icons", - "components/mermaid-diagrams", - "components/panel", - "components/steps", - "components/tabs", - "components/tooltips", - "components/update", - "components/banner" + "create/text", + "create/code", + "create/image-embeds", + "create/files", + "create/list-table", + { + "group": "Components", + "pages": [ + "components/accordions", + "components/banner", + "components/callouts", + "components/cards", + "components/code-groups", + "components/columns", + "components/examples", + "components/expandables", + "components/fields", + "components/frames", + "components/icons", + "components/mermaid-diagrams", + "components/panel", + "components/responses", + "components/steps", + "components/tabs", + "components/tooltips", + "components/update" + ] + }, + "create/reusable-snippets", + "create/broken-links", + "create/changelogs" ] }, { - "group": "API pages", + "group": "Document APIs", + "icon": "file-json", "pages": [ "api-playground/overview", "api-playground/openapi-setup", - "api-playground/migrating-from-mdx", + "api-playground/complex-data-types", + "api-playground/adding-sdk-examples", + "api-playground/managing-page-visibility", + "api-playground/multiple-responses", { - "group": "Customization", - "icon": "wrench", + "group": "MDX", "pages": [ - "api-playground/customization/complex-data-types", - "api-playground/customization/adding-sdk-examples", - "api-playground/customization/managing-page-visibility", - "api-playground/customization/multiple-responses" + "api-playground/mdx/configuration", + "api-playground/mdx/authentication" ] }, { "group": "AsyncAPI", - "icon": "webhook", "pages": [ "api-playground/asyncapi/setup", "api-playground/asyncapi/playground" ] }, - { - "group": "MDX", - "icon": "markdown", - "pages": [ - "api-playground/mdx/configuration", - "api-playground/mdx/authentication" - ] - }, "api-playground/troubleshooting" ] }, { - "group": "Authentication and personalization", + "group": "Deploy", + "icon": "boxes", "pages": [ - "authentication-personalization/authentication-setup", - "authentication-personalization/personalization-setup" - ] - }, - { - "group": "Guides", - "pages": [ - "guides/migration", - { - "group": "Analytics dashboard", - "icon": "chart-line", - "pages": [ - "analytics/overview", - "analytics/feedback", - "analytics/search", - "analytics/improving-docs" - ] - }, - "react-components", - "settings/custom-scripts", - "settings/seo", - "guides/changelogs", - "guides/hidden-pages", - "settings/broken-links", - "settings/custom-404-page", - "guides/monorepo", - { - "group": "Custom Subdirectory", - "icon": "folder", - "pages": [ - "advanced/subpath/cloudflare", - "advanced/subpath/route53-cloudfront", - "advanced/subpath/vercel", - "guides/csp-configuration" - ] - }, + "deploy/deployments", + "deploy/preview-deployments", { - "group": "Dashboard Access", - "icon": "gauge", + "group": "Custom subdirectory", "pages": [ - "advanced/dashboard/sso", - "advanced/dashboard/permissions", - "advanced/dashboard/roles" + "deploy/cloudflare", + "deploy/route53-cloudfront", + "deploy/vercel", + "deploy/reverse-proxy", + "deploy/csp-configuration" ] }, - "guides/deployments", - "pdf-exports", - "contact-support" + "deploy/authentication-setup", + "deploy/personalization-setup", + "deploy/monorepo", + "deploy/ci", + "deploy/github", + "deploy/gitlab" ] }, { - "group": "Integrations", + "group": "Optimize", + "icon": "wrench", "pages": [ { - "group": "Analytics", - "icon": "chart-no-axes-combined", - "pages": [ - "integrations/analytics/overview", - "integrations/analytics/amplitude", - "integrations/analytics/clearbit", - "integrations/analytics/fathom", - "integrations/analytics/google-analytics", - "integrations/analytics/google-tag-manager", - "integrations/analytics/heap", - "integrations/analytics/hightouch", - "integrations/analytics/hotjar", - "integrations/analytics/koala", - "integrations/analytics/logrocket", - "integrations/analytics/mixpanel", - "integrations/analytics/pirsch", - "integrations/analytics/plausible", - "integrations/analytics/posthog", - "integrations/analytics/segment" - ] - }, - { - "group": "SDKs", - "icon": "folder-code", + "group": "AI", "pages": [ - "integrations/sdks/speakeasy", - "integrations/sdks/stainless" + "ai/assistant", + "ai/agent", + "ai/llmstxt", + "ai/contextual-menu", + "ai/model-context-protocol", + "ai/markdown-export" ] }, { - "group": "Support", - "icon": "messages-square", + "group": "Analytics", "pages": [ - "integrations/support/overview", - "integrations/support/intercom", - "integrations/support/front" + "analytics/overview", + "analytics/feedback", + "analytics/search" ] }, + "optimize/seo", + "optimize/pdf-exports", { - "group": "Privacy", - "icon": "folder-lock", + "group": "Integrations", "pages": [ - "integrations/privacy/overview", - "integrations/privacy/osano" + { + "group": "Analytics", + "pages": [ + "integrations/analytics/overview", + "integrations/analytics/amplitude", + "integrations/analytics/clearbit", + "integrations/analytics/fathom", + "integrations/analytics/google-analytics", + "integrations/analytics/google-tag-manager", + "integrations/analytics/heap", + "integrations/analytics/hightouch", + "integrations/analytics/hotjar", + "integrations/analytics/koala", + "integrations/analytics/logrocket", + "integrations/analytics/mixpanel", + "integrations/analytics/pirsch", + "integrations/analytics/plausible", + "integrations/analytics/posthog", + "integrations/analytics/segment" + ] + }, + { + "group": "SDKs", + "pages": [ + "integrations/sdks/speakeasy", + "integrations/sdks/stainless" + ] + }, + { + "group": "Support", + "pages": [ + "integrations/support/overview", + "integrations/support/intercom", + "integrations/support/front" + ] + }, + { + "group": "Privacy", + "pages": [ + "integrations/privacy/overview", + "integrations/privacy/osano" + ] + } ] } ] + } + ] + }, + { + "tab": "Guides", + "groups": [ + { + "group": "AI", + "icon": "bot", + "pages": [ + "guides/geo", + "guides/claude-code", + "guides/cursor", + "guides/windsurf" + ] + }, + { + "group": "API docs", + "icon": "file-json", + "pages": [ + "guides/migrating-from-mdx" + ] + }, + { + "group": "Analytics", + "icon": "chart-line", + "pages": [ + "guides/improving-docs" + ] }, { - "group": "Version control and CI/CD", + "group": "Git", + "icon": "git-merge", "pages": [ - "settings/github", - "settings/gitlab", - "settings/ci", - "settings/preview-deployments" + "guides/git-concepts", + "guides/branches" ] } ] @@ -248,12 +275,12 @@ "groups": [ { "group": "API Reference", - "pages": [ - "api-reference/introduction" - ] + "icon": "file-json", + "pages": ["api-reference/introduction"] }, { "group": "Admin", + "icon": "activity", "pages": [ "api-reference/update/trigger", "api-reference/update/status" @@ -261,6 +288,7 @@ }, { "group": "Agent", + "icon": "pen-line", "pages": [ "api-reference/agent/create-agent-job", "api-reference/agent/get-agent-job", @@ -269,6 +297,7 @@ }, { "group": "Assistant", + "icon": "bot-message-square", "pages": [ "api-reference/assistant/create-assistant-message", "api-reference/assistant/search" @@ -281,9 +310,8 @@ "groups": [ { "group": "Changelog", - "pages": [ - "changelog" - ] + "icon": "calendar", + "pages": ["changelog"] } ] } @@ -558,9 +586,7 @@ "groups": [ { "group": "Journal des modifications", - "pages": [ - "fr/changelog" - ] + "pages": ["fr/changelog"] } ] } @@ -802,9 +828,7 @@ "groups": [ { "group": "Referencia de la API", - "pages": [ - "es/api-reference/introduction" - ] + "pages": ["es/api-reference/introduction"] }, { "group": "Administrador", @@ -1079,9 +1103,7 @@ "groups": [ { "group": "API 参考", - "pages": [ - "zh/api-reference/introduction" - ] + "pages": ["zh/api-reference/introduction"] }, { "group": "管理员", @@ -1182,8 +1204,8 @@ "href": "https://www.mintlify.com/pricing" }, { - "label": "Guides", - "href": "https://www.mintlify.com/guides" + "label": "Contact support", + "href": "https://www.mintlify.com/docs/contact-support" }, { "label": "Feature Requests", @@ -1227,13 +1249,7 @@ "background": "/images/thumbnail/background.svg" }, "contextual": { - "options": [ - "copy", - "chatgpt", - "claude", - "cursor", - "vscode" - ] + "options": ["copy", "chatgpt", "claude", "cursor", "vscode"] }, "redirects": [ { @@ -1296,10 +1312,6 @@ "source": "/content/components/update", "destination": "/components/update" }, - { - "source": "/api-playground/openapi/advanced-features", - "destination": "/api-playground/customization" - }, { "source": "/api-playground/openapi/setup", "destination": "/api-playground/openapi-setup" @@ -1322,55 +1334,55 @@ }, { "source": "settings/authentication-personalization/authentication", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/personalization", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "settings/authentication-personalization/partial-authentication", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/sending-data", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "authentication-personalization/partial-authentication-setup", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "authentication-personalization/sending-data", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "settings/authentication-personalization/authentication-setup/jwt", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/authentication-setup/oauth", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/authentication-setup/mintlify", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/authentication-setup/password", - "destination": "authentication-personalization/authentication-setup" + "destination": "deploy/authentication-setup" }, { "source": "settings/authentication-personalization/personalization-setup/jwt", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "settings/authentication-personalization/personalization-setup/oauth", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "settings/authentication-personalization/personalization-setup/shared-session", - "destination": "authentication-personalization/personalization-setup" + "destination": "deploy/personalization-setup" }, { "source": "ai-ingestion", @@ -1387,6 +1399,178 @@ { "source": "guides/analytics", "destination": "analytics/overview" + }, + { + "source": "guides/assistant", + "destination": "ai/assistant" + }, + { + "source": "api-playground/customization/adding-sdk-examples", + "destination": "api-playground/adding-sdk-examples" + }, + { + "source": "api-playground/customization/complex-data-types", + "destination": "api-playground/complex-data-types" + }, + { + "source": "api-playground/customization/managing-page-visibility", + "destination": "api-playground/managing-page-visibility" + }, + { + "source": "api-playground/customization/multiple-responses", + "destination": "api-playground/multiple-responses" + }, + { + "source": "settings/broken-links", + "destination": "create/broken-links" + }, + { + "source": "guides/changelogs", + "destination": "create/changelogs" + }, + { + "source": "code", + "destination": "create/code" + }, + { + "source": "components/files", + "destination": "create/files" + }, + { + "source": "image-embeds", + "destination": "create/image-embeds" + }, + { + "source": "list-table", + "destination": "create/list-table" + }, + { + "source": "reusable-snippets", + "destination": "create/reusable-snippets" + }, + { + "source": "text", + "destination": "create/text" + }, + { + "source": "settings/custom-404-page", + "destination": "customize/custom-404-page" + }, + { + "source": "settings/custom-domain", + "destination": "customize/custom-domain" + }, + { + "source": "settings/custom-scripts", + "destination": "customize/custom-scripts" + }, + { + "source": "react-components", + "destination": "customize/react-components" + }, + { + "source": "themes", + "destination": "customize/themes" + }, + { + "source": "advanced/dashboard/permissions", + "destination": "dashboard/permissions" + }, + { + "source": "advanced/dashboard/roles", + "destination": "dashboard/roles" + }, + { + "source": "advanced/dashboard/sso", + "destination": "dashboard/sso" + }, + { + "source": "settings/ci", + "destination": "deploy/ci" + }, + { + "source": "advanced/subpath/cloudflare", + "destination": "deploy/cloudflare" + }, + { + "source": "guides/csp-configuration", + "destination": "deploy/csp-configuration" + }, + { + "source": "guides/deployments", + "destination": "deploy/deployments" + }, + { + "source": "settings/github", + "destination": "deploy/github" + }, + { + "source": "settings/gitlab", + "destination": "deploy/gitlab" + }, + { + "source": "guides/monorepo", + "destination": "deploy/monorepo" + }, + { + "source": "settings/preview-deployments", + "destination": "deploy/preview-deployments" + }, + { + "source": "guides/reverse-proxy", + "destination": "deploy/reverse-proxy" + }, + { + "source": "advanced/subpath/route53-cloudfront", + "destination": "deploy/route53-cloudfront" + }, + { + "source": "advanced/subpath/vercel", + "destination": "deploy/vercel" + }, + { + "source": "editor/branches", + "destination": "guides/branches" + }, + { + "source": "editor/git-concepts", + "destination": "guides/git-concepts" + }, + { + "source": "analytics/improving-docs", + "destination": "guides/improving-docs" + }, + { + "source": "api-playground/migrating-from-mdx", + "destination": "guides/migrating-from-mdx" + }, + { + "source": "guides/migration", + "destination": "migration" + }, + { + "source": "settings/seo", + "destination": "optimize/seo" + }, + { + "source": "guides/hidden-page-example", + "destination": "organize/hidden-page-example" + }, + { + "source": "guides/hidden-pages", + "destination": "organize/hidden-pages" + }, + { + "source": "navigation", + "destination": "organize/navigation" + }, + { + "source": "pages", + "destination": "organize/pages" + }, + { + "source": "settings", + "destination": "organize/settings" } ], "integrations": { @@ -1397,4 +1581,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} \ No newline at end of file +} diff --git a/editor/getting-started.mdx b/editor/getting-started.mdx index 5984aacfa..73763ee79 100644 --- a/editor/getting-started.mdx +++ b/editor/getting-started.mdx @@ -101,7 +101,7 @@ Markdown mode provides direct access to the underlying `MDX` code of your docume ## Next steps -- Learn fundamental [Git concepts](/editor/git-concepts). -- Learn best practices for collaborating with [branches](/editor/branches). +- Learn fundamental [Git concepts](/guides/git-concepts). +- Learn best practices for collaborating with [branches](/guides/branches). - Explore [content management](/editor/content-management) with the web editor. - Understand [publishing options](/editor/publishing) for different scenarios. diff --git a/editor/troubleshooting.mdx b/editor/troubleshooting.mdx index 6047a0a33..1e0aecdd4 100644 --- a/editor/troubleshooting.mdx +++ b/editor/troubleshooting.mdx @@ -27,7 +27,7 @@ Find solutions to common issues you might encounter while using the web editor. **Solutions:** 1. Verify you have correct access to the repository. 2. Check if your Git integration is properly configured. - 3. Review the [Editor Permissions](/advanced/dashboard/permissions) documentation. + 3. Review the [Editor Permissions](/dashboard/permissions) documentation. **Possible causes:** diff --git a/editor/branches.mdx b/guides/branches.mdx similarity index 100% rename from editor/branches.mdx rename to guides/branches.mdx diff --git a/guides/claude-code.mdx b/guides/claude-code.mdx index fb9efe8da..6c0565558 100644 --- a/guides/claude-code.mdx +++ b/guides/claude-code.mdx @@ -1,7 +1,6 @@ --- title: "Claude Code" description: "Configure Claude Code to help write, review, and update your docs" -icon: "asterisk" --- Claude Code is an agentic command line tool that can help you maintain your documentation. It can write new content, review existing pages, and keep docs up to date. diff --git a/guides/cursor.mdx b/guides/cursor.mdx index 862c1441f..01e03813e 100644 --- a/guides/cursor.mdx +++ b/guides/cursor.mdx @@ -1,7 +1,6 @@ --- title: "Cursor" description: "Configure Cursor to be your writing assistant" -icon: "box" --- Transform Cursor into a documentation expert that knows your components, style guide, and best practices. diff --git a/guides/geo.mdx b/guides/geo.mdx index d4294ad19..cf2d05f16 100644 --- a/guides/geo.mdx +++ b/guides/geo.mdx @@ -2,7 +2,6 @@ title: "GEO guide: Optimize docs for AI search and answer engines" sidebarTitle: "GEO" description: "Make your documentation more discoverable and cited more frequently by AI tools" -icon: "cpu" --- Optimize your documentation for both traditional search engines and AI-powered answer engines like ChatGPT, Perplexity, and Google AI Overviews. diff --git a/editor/git-concepts.mdx b/guides/git-concepts.mdx similarity index 97% rename from editor/git-concepts.mdx rename to guides/git-concepts.mdx index 8f3d989dc..64f903391 100644 --- a/editor/git-concepts.mdx +++ b/guides/git-concepts.mdx @@ -39,7 +39,7 @@ The web editor performs some Git operations behind the scenes. Understanding the ## How the web editor uses Git -The web editor connects to your Git repository through the [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab) and automates common Git operations. +The web editor connects to your Git repository through the [GitHub App](/deploy/github) or [GitLab integration](/deploy/gitlab) and automates common Git operations. When you: diff --git a/analytics/improving-docs.mdx b/guides/improving-docs.mdx similarity index 100% rename from analytics/improving-docs.mdx rename to guides/improving-docs.mdx diff --git a/api-playground/migrating-from-mdx.mdx b/guides/migrating-from-mdx.mdx similarity index 99% rename from api-playground/migrating-from-mdx.mdx rename to guides/migrating-from-mdx.mdx index 69a7fe229..8490584e1 100644 --- a/api-playground/migrating-from-mdx.mdx +++ b/guides/migrating-from-mdx.mdx @@ -2,7 +2,6 @@ title: "Migrating MDX API pages to OpenAPI navigation" sidebarTitle: "Migrating from MDX" description: "Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation" -icon: "arrow-big-right-dash" --- If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation. diff --git a/guides/windsurf.mdx b/guides/windsurf.mdx index ed2d80814..e00fcdd38 100644 --- a/guides/windsurf.mdx +++ b/guides/windsurf.mdx @@ -1,7 +1,6 @@ --- title: "Windsurf" description: "Configure Windsurf to be your writing assistant" -icon: "waves" --- Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories. diff --git a/index.mdx b/index.mdx index 92bfd2201..4e48f2ae4 100644 --- a/index.mdx +++ b/index.mdx @@ -1,7 +1,6 @@ --- title: "Introduction" description: "Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers." -icon: "book-open" mode: "custom" --- diff --git a/installation.mdx b/installation.mdx index 69a05574f..2a583f1dd 100644 --- a/installation.mdx +++ b/installation.mdx @@ -1,8 +1,6 @@ --- title: "CLI installation" -sidebarTitle: "Installation" description: "Install the CLI to preview and develop your docs locally" -icon: "terminal" --- - By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/authentication-personalization/authentication-setup). + By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/deploy/authentication-setup). - **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. diff --git a/guides/hidden-pages.mdx b/organize/hidden-pages.mdx similarity index 93% rename from guides/hidden-pages.mdx rename to organize/hidden-pages.mdx index 2c91872bb..7d8c1ffa6 100644 --- a/guides/hidden-pages.mdx +++ b/organize/hidden-pages.mdx @@ -1,14 +1,13 @@ --- title: "Hidden pages" description: "Exclude pages from your navigation" -icon: "eye-closed" --- Hidden pages are removed from your site's navigation but remain publicly accessible to anyone who knows their URL. Use hidden pages for content that you want to be accessible on your site or referenced as context for AI tools, but not discoverable through the navigation. -For content requiring strict access control, you must configure [authentication](/authentication-personalization/authentication-setup). +For content requiring strict access control, you must configure [authentication](/deploy/authentication-setup). If you want to hide pages for specific groups of users, use personalization to control [page visibility](/authentication-personalization/overview#page-visibility). @@ -18,7 +17,7 @@ A page is hidden if it is not included in your `docs.json` navigation. To hide a Hidden pages use the same URL structure as regular pages based on their file path. For example, `guides/hidden-page.mdx` would be accessible at `docs.yoursite.com/guides/hidden-page`. -See an [example of a hidden page](/guides/hidden-page-example). +See an [example of a hidden page](/organize/hidden-page-example). Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages. diff --git a/navigation.mdx b/organize/navigation.mdx similarity index 99% rename from navigation.mdx rename to organize/navigation.mdx index bbc801c64..27ea5cc95 100644 --- a/navigation.mdx +++ b/organize/navigation.mdx @@ -1,7 +1,6 @@ --- title: "Navigation" description: "Structure and customize your documentation's navigation hierarchy" -icon: "map" --- The [navigation](settings#param-navigation) property in `docs.json` controls the structure and information hierarchy of your documentation. diff --git a/pages.mdx b/organize/pages.mdx similarity index 98% rename from pages.mdx rename to organize/pages.mdx index 26faa3e9a..51b33e12d 100644 --- a/pages.mdx +++ b/organize/pages.mdx @@ -1,7 +1,6 @@ --- title: "Pages" description: "Pages are the building blocks of your documentation" -icon: "letter-text" keywords: ["tags", "tag"] --- @@ -153,7 +152,7 @@ Most SEO meta tags are automatically generated. You can set SEO meta tags manual --- ``` -See [SEO](/settings/seo) for complete SEO metadata options. +See [SEO](/optimize/seo) for complete SEO metadata options. ## Internal search keywords diff --git a/settings.mdx b/organize/settings.mdx similarity index 99% rename from settings.mdx rename to organize/settings.mdx index 4f01d6307..87fc5435d 100644 --- a/settings.mdx +++ b/organize/settings.mdx @@ -1,7 +1,6 @@ --- title: "Global settings" description: "Configure site-wide settings with the `docs.json` file" -icon: "settings-2" keywords: ["docs.json", "settings", "customization", "configuration"] --- @@ -704,7 +703,7 @@ See [Themes](themes) for more information. - Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/settings/seo#common-meta-tags-reference) for options. + Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/optimize/seo#common-meta-tags-reference) for options. Specify which pages search engines should index. Choose `navigable` to index only pages that are in your `docs.json` navigation or choose `all` to index every page. Defaults to `navigable`. diff --git a/quickstart.mdx b/quickstart.mdx index 076b50534..c6ee26b90 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,7 +1,6 @@ --- title: "Quickstart" description: "Deploy your documentation in minutes" -icon: "rocket" --- This quickstart guide shows you how to set up and deploy your documentation site in minutes.