From 413627b0670122915eb246ad37bc08ff21d49fa9 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sun, 30 Nov 2025 04:06:07 +0000 Subject: [PATCH 1/5] Update guides/overview.mdx --- guides/overview.mdx | 63 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 guides/overview.mdx diff --git a/guides/overview.mdx b/guides/overview.mdx new file mode 100644 index 000000000..ea681ae42 --- /dev/null +++ b/guides/overview.mdx @@ -0,0 +1,63 @@ +--- +title: "Guides overview" +description: "Learn how to create effective documentation with best practices, AI tools, and Git workflows." +--- + + + This page provides a walkthrough of the guides available to help you build and maintain high-quality documentation. + + +The Guides section contains practical advice for creating documentation that serves your users. Whether you're starting from scratch or improving existing docs, these guides help you make informed decisions. + +## What you'll find + +### AI tools + +Use AI-powered tools to accelerate your documentation workflow: + +- [Automate with Agent](/guides/automate-agent): Set up automated documentation updates using the Mintlify Agent. +- [Embed the Assistant](/guides/assistant-embed): Add an AI assistant to help users find answers. +- [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Integrate AI coding assistants with your docs workflow. +- [Geo-based routing](/guides/geo): Configure geographic routing for AI features. + +### API documentation + +- [Migrate from MDX](/guides/migrating-from-mdx): Move your API documentation from MDX to OpenAPI specifications. + +### Best practices + +Build documentation that users love: + +- [Accessibility](/guides/accessibility): Make your docs accessible to all users. +- [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. +- [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve. +- [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date. +- [Media](/guides/media): Add images, videos, and other media effectively. +- [Organize navigation](/guides/navigation): Design information architecture that works. +- [SEO](/guides/seo): Optimize your docs for search engines. +- [Style and tone](/guides/style-and-tone): Write with a consistent voice. +- [Understand your audience](/guides/understand-your-audience): Research and serve your users' needs. + +### Git workflows + +Manage your documentation with version control: + +- [Git concepts](/guides/git-concepts): Learn the fundamentals of Git for documentation. +- [Branches](/guides/branches): Use branches to manage documentation changes. + +## Where to start + + + + Start with content types to understand how to structure your docs. + + + Learn how to use metrics and feedback to make your docs better. + + + Automate documentation updates with the Mintlify Agent. + + + Learn Git workflows for collaborative documentation. + + From a487bf7831e1c671652b1c553991976c21e3da0d Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sun, 30 Nov 2025 04:06:20 +0000 Subject: [PATCH 2/5] Update docs.json --- docs.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs.json b/docs.json index 60d91773a..fe3c88394 100644 --- a/docs.json +++ b/docs.json @@ -222,6 +222,13 @@ { "tab": "Guides", "groups": [ + { + "group": "Overview", + "icon": "book-open", + "pages": [ + "guides/overview" + ] + }, { "group": "AI", "icon": "bot", From 4a6c8710699be4c820785412e71ed31b11c6d7af Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:17:26 -0800 Subject: [PATCH 3/5] copyedits --- docs.json | 2 +- guides/index.mdx | 61 +++++++++++++++++++++++++++++++++++++++++++ guides/overview.mdx | 63 --------------------------------------------- 3 files changed, 62 insertions(+), 64 deletions(-) create mode 100644 guides/index.mdx delete mode 100644 guides/overview.mdx diff --git a/docs.json b/docs.json index fe3c88394..609e41187 100644 --- a/docs.json +++ b/docs.json @@ -226,7 +226,7 @@ "group": "Overview", "icon": "book-open", "pages": [ - "guides/overview" + "guides/index" ] }, { diff --git a/guides/index.mdx b/guides/index.mdx new file mode 100644 index 000000000..35f7c555e --- /dev/null +++ b/guides/index.mdx @@ -0,0 +1,61 @@ +--- +title: "Guides overview" +description: "Learn how to create effective documentation with best practices and workflows." +--- + +The guides in this section contain advice for creating documentation that helps your users succeed. Whether you're starting from scratch or improving existing docs, these guides help you plan, write, and maintain your documentation. + +Above all else, consider your users' needs and goals. Document what helps them use your product and get back to their tasks. + +## AI tools + +Use AI-powered tools to accelerate your documentation workflow. + +- [Automate documentation updates](/guides/automate-agent): Tutorial that teaches how to set up automated documentation updates using the agent. +- [Build an in-app assistant](/guides/assistant-embed): Tutorial that teaches how to add an AI chat bot in a React app to help users find answers from your documentation. +- [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Guides for using AI coding assistants to maintain documentation. +- [GEO](/guides/geo): Best practices for optimizing your documentation for AI search and answer engines. + +## API documentation + +Create API documentation that lets users test and learn how to use your API, and is easy to maintain. + +- [Migrate from MDX to OAS](/guides/migrating-from-mdx): Move your API documentation from individual MDX pages to autogenerated pages from an OpenAPI specifications. + +## Best practices + +Make your documentation best in class. + +- [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible. +- [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. +- [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation. +- [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date. +- [Media](/guides/media): Add images, videos, and other media effectively while managing maintenance burden. +- [Organize navigation](/guides/navigation): Design information architecture that works for your users. +- [SEO](/guides/seo): Optimize your docs for search engines. +- [Style and tone](/guides/style-and-tone): Write with a consistent voice. +- [Understand your audience](/guides/understand-your-audience): Research and serve your users' needs and goals. + +## Git workflows + +Understand Git to get the most out of Mintlify and a docs-as-code approach to documentation. + +- [Git concepts](/guides/git-concepts): Learn the fundamentals of Git for documentation. +- [Branches](/guides/branches): Use branches to manage documentation changes. + +## Where to start + + + + Learn about content types to understand how to structure your docs. + + + Learn how to use metrics and feedback to make your docs better. + + + Automate documentation updates with the agent. + + + Learn Git workflows for collaborative documentation. + + diff --git a/guides/overview.mdx b/guides/overview.mdx deleted file mode 100644 index ea681ae42..000000000 --- a/guides/overview.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Guides overview" -description: "Learn how to create effective documentation with best practices, AI tools, and Git workflows." ---- - - - This page provides a walkthrough of the guides available to help you build and maintain high-quality documentation. - - -The Guides section contains practical advice for creating documentation that serves your users. Whether you're starting from scratch or improving existing docs, these guides help you make informed decisions. - -## What you'll find - -### AI tools - -Use AI-powered tools to accelerate your documentation workflow: - -- [Automate with Agent](/guides/automate-agent): Set up automated documentation updates using the Mintlify Agent. -- [Embed the Assistant](/guides/assistant-embed): Add an AI assistant to help users find answers. -- [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Integrate AI coding assistants with your docs workflow. -- [Geo-based routing](/guides/geo): Configure geographic routing for AI features. - -### API documentation - -- [Migrate from MDX](/guides/migrating-from-mdx): Move your API documentation from MDX to OpenAPI specifications. - -### Best practices - -Build documentation that users love: - -- [Accessibility](/guides/accessibility): Make your docs accessible to all users. -- [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. -- [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve. -- [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date. -- [Media](/guides/media): Add images, videos, and other media effectively. -- [Organize navigation](/guides/navigation): Design information architecture that works. -- [SEO](/guides/seo): Optimize your docs for search engines. -- [Style and tone](/guides/style-and-tone): Write with a consistent voice. -- [Understand your audience](/guides/understand-your-audience): Research and serve your users' needs. - -### Git workflows - -Manage your documentation with version control: - -- [Git concepts](/guides/git-concepts): Learn the fundamentals of Git for documentation. -- [Branches](/guides/branches): Use branches to manage documentation changes. - -## Where to start - - - - Start with content types to understand how to structure your docs. - - - Learn how to use metrics and feedback to make your docs better. - - - Automate documentation updates with the Mintlify Agent. - - - Learn Git workflows for collaborative documentation. - - From 846790637656f9b681330ef46b7918d2ac7a5052 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:18:18 -0800 Subject: [PATCH 4/5] Update index.mdx --- guides/index.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/guides/index.mdx b/guides/index.mdx index 35f7c555e..bc7e74f9d 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -7,7 +7,9 @@ The guides in this section contain advice for creating documentation that helps Above all else, consider your users' needs and goals. Document what helps them use your product and get back to their tasks. -## AI tools +## Topics + +### AI tools Use AI-powered tools to accelerate your documentation workflow. @@ -16,13 +18,13 @@ Use AI-powered tools to accelerate your documentation workflow. - [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Guides for using AI coding assistants to maintain documentation. - [GEO](/guides/geo): Best practices for optimizing your documentation for AI search and answer engines. -## API documentation +### API documentation Create API documentation that lets users test and learn how to use your API, and is easy to maintain. - [Migrate from MDX to OAS](/guides/migrating-from-mdx): Move your API documentation from individual MDX pages to autogenerated pages from an OpenAPI specifications. -## Best practices +### Best practices Make your documentation best in class. @@ -36,7 +38,7 @@ Make your documentation best in class. - [Style and tone](/guides/style-and-tone): Write with a consistent voice. - [Understand your audience](/guides/understand-your-audience): Research and serve your users' needs and goals. -## Git workflows +### Git workflows Understand Git to get the most out of Mintlify and a docs-as-code approach to documentation. From af99ca20549a38996b7c939a3d060cf06c71827a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:20:42 -0800 Subject: [PATCH 5/5] update title --- guides/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/index.mdx b/guides/index.mdx index bc7e74f9d..37303b7fe 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -1,5 +1,5 @@ --- -title: "Guides overview" +title: "Guides" description: "Learn how to create effective documentation with best practices and workflows." ---