Merge branch 'main' into web-editor-guide

Author: ethanpalm

changelog.mdx

@@ -6,11 +6,12 @@ mode: "center"
 
 <Update label="May 2025">
   ## API playground stability updates
+
   - Search to find an endpoint
   - Indicate a deprecated endpoint with a tag
   - Hide auto-generated API pages from navigation
   - Upload multipart or form data files
-  
+
   Learn more at [API playground docs.](/api-playground/)
 
   ## `mint update`
@@ -21,9 +22,8 @@ mode: "center"
   ## Web Editor 3.0
 
   <Frame>
-  ![Webeditor3 Jpe](/images/webeditor3.jpeg)
+    ![Webeditor3 Jpe](/images/webeditor3.jpeg)
   </Frame>
-  
   Overhauled usability in the WYSIWYG editor.
 
   **Major improvements**
@@ -173,12 +173,12 @@ mode: "center"
 </Update>
 
 <Update label="November 2024">
-  ## AI Assistant
+  ## AI Writer
 
   <Frame>
     ![AI Assistant](/images/changelog/ai-assistant.jpg)
   </Frame>
-  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.
+  You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the writer will propose changes by generating a pull request.
 
   ## GitLab Integration Upgrade
 
@@ -461,4 +461,4 @@ mode: "center"
   - 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.
-</Update>
+</Update>

code.mdx

@@ -19,7 +19,9 @@ To denote a `word` or `phrase` as code, enclose it in backticks (`).
 
 ### Code blocks
 
-Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Specify the programming language for syntax highlighting and to enable meta options. Add any meta options, like a title or icon, after the language.
+Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Code blocks are copyable, and if you have the assistant enabled, users can ask AI to explain the code.
+
+Specify the programming language for syntax highlighting and to enable meta options. Add any meta options, like a title or icon, after the language.
 
 ```java HelloWorld.java lines icon="java"
 class HelloWorld {

docs.json

@@ -112,6 +112,7 @@
             "group": "Guides",
             "pages": [
               "guides/migration",
+              "guides/assistant",
               "mcp",
               "guides/cursor",
               "translations",

guides/assistant.mdx

@@ -16,11 +16,13 @@ If you want to hide pages for specific groups of users, use personalization to c
 
 A page is hidden if it is not included in your `docs.json` navigation. To hide a page, remove it from your navigation structure.
 
+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`.
+
 <Note>
-Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
+  Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
 </Note>
 
-## Search, SEO, and AI context
+## Search, SEO, and AI indexing
 
 By default, hidden pages are excluded from indexing for search engines, internal search within your docs, and as context for the AI assistant. To include hidden pages in search results and as context for the assistant, add the `seo` property to your `docs.json`:
 
@@ -30,4 +32,4 @@ By default, hidden pages are excluded from indexing for search engines, internal
 }
 ```
 
-To exclude a specific page, add `noindex: "true"` to its frontmatter.
+To exclude a specific page, add `noindex: "true"` to its frontmatter.

guides/hidden-pages.mdx

@@ -17,7 +17,7 @@ icon: "terminal"
 ## Installing the CLI
 
 <Info>
-  **Prerequisite**: Please install [Node.js](https://nodejs.org/en) (version 19 or higher) before proceeding.
+  **Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding.
 </Info>
 
 <Steps>
@@ -159,7 +159,7 @@ If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugin
     This may be due to an outdated version of node. Try the following:
 
     1. Remove the currently-installed version of the mint CLI: `npm remove -g mint`
-    2. Upgrade to Node v19 or higher.
+    2. Upgrade to Node.js.
     3. Reinstall the mint CLI: `npm install -g mint`
   </Accordion>
   <Accordion title="Issue: Encountering an unknown error">

images/assistant/assistant-button-dark.png

@@ -576,28 +576,25 @@ The syntax for `docs.json` is below. You only need to include entries for the pl
 ```
 ## Analytics events
 
-We send the following events to your analytics provider.
+We send the following events to your analytics provider. All events use the `docs.` prefix.
 
-| Event name                        | Description                                                        |
-|:-----------------------------------|:-------------------------------------------------------------------|
-| `accordion_close`                  | When a user closes an accordion.                                   |
-| `accordion_open`                   | When a user opens an accordion.                                    |
-| `api_playground_call`              | When a user calls an API in the API playground.                    |
-| `code_block_copy`                  | When a user copies code from a code block.                         |
-| `cta_click`                        | When a user clicks a call to action.                               |
-| `expandable_close`                 | When a user closes an expandable.                                  |
-| `expandable_open`                  | When a user opens an expandable.                                   |
-| `header_nav_item_click`            | When a user clicks a header navigation item.                       |
-| `pageview`                         | When a user views a page.                                          |
-| `powered_by_mintlify_click`        | When a user clicks the "Powered by Mintlify" link.                 |
-| `scroll_to_bottom`                 | When a user scrolls to the bottom of a page.                       |
-| `thumb_vote`                       | When a user votes (thumbs up or down) on a page.                   |
-| `ai_chat_citation_click`           | When a user clicks a citation in a chat.                           |
-| `ai_chat_feedback_positive_click`  | When a user clicks the positive feedback button in a chat.         |
-| `ai_chat_feedback_negative_click`  | When a user clicks the negative feedback button in a chat.         |
-| `chat_completed`                   | When a chat session is completed.                                  |
-| `chat_enter`                       | When a user initiates a chat.                                      |
-| `chat_followup`                    | When a user sends a follow up message.                             |
-| `chat_shared`                      | When a user shares a chat conversation.                            |
-| `search_close`                     | When a user closes the search bar.                                 |
-| `search_result_click`              | When a user clicks a search result.                                |
+| Event name                             | Description                                                         |
+|:---------------------------------------|:--------------------------------------------------------------------|
+| `docs.accordion.close`                  | When a user closes an accordion.                                   |
+| `docs.accordion.open`                   | When a user opens an accordion.                                    |
+| `docs.api_playground.request`           | When a user calls an API in the API playground.                    |
+| `docs.code_block.copy`                  | When a user copies code from a code block.                         |
+| `docs.code_block.ask_ai`                | When a user asks the assistant to explain a code block.            |
+| `docs.navitem.cta_click`                | When a user clicks a call to action.                               |
+| `docs.expandable.close`                 | When a user closes an expandable.                                  |
+| `docs.expandable.open`                  | When a user opens an expandable.                                   |
+| `docs.navitem.click`                    | When a user clicks a header navigation item.                       |
+| `docs.footer.powered_by_mintlify_click` | When a user clicks the "Powered by Mintlify" link.                 |
+| `docs.assistant.source_click`           | When a user clicks a citation in a chat.                           |
+| `docs.assistant.thumbs_up`              | When a user clicks the positive feedback button in a chat.         |
+| `docs.assistant.thumbs_down`            | When a user clicks the negative feedback button in a chat.         |
+| `docs.assistant.completed`              | When a chat session is completed.                                  |
+| `docs.assistant.enter`                  | When a user initiates a chat.                                      |
+| `docs.assistant.shared`                 | When a user shares a chat conversation.                            |
+| `docs.search.close`                     | When a user closes the search bar.                                 |
+| `docs.search.result_click`              | When a user clicks a search result.                                |

images/assistant/assistant-button-light.png

@@ -100,7 +100,7 @@ pnpm add -g mint
 </CodeGroup>
 
 <Info>
-  You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide.
+  You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide.
 </Info>
 
 ### Edit the Documentation
@@ -224,16 +224,19 @@ Enter your domain (for example, `docs.yourcompany.com`) and follow the provided
 
 Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
 
-<Card title="Customize Your Theme" icon="paintbrush" href="themes" horizontal>
+<Card title="Configure your global settings" icon="settings" href="settings" horizontal>
+  Configure site-wide styling, navigation, integrations, and more with the `docs.json` file.
+</Card>
+<Card title="Customize your theme" icon="paintbrush" href="themes" horizontal>
   Learn how to customize colors, fonts, and the overall appearance of your documentation site.
 </Card>
-<Card title="Organize Navigation" icon="map" href="navigation#overview" horizontal>
+<Card title="Organize navigation" icon="map" href="navigation" horizontal>
   Structure your documentation with intuitive navigation to help users find what they need.
 </Card>
-<Card title="Add Interactive Components" icon="puzzle" href="/components/accordions" horizontal>
+<Card title="Add interactive components" icon="puzzle" href="/components/accordions" horizontal>
   Enhance your documentation with interactive components like accordions, tabs, and code samples.
 </Card>
-<Card title="Set Up API References" icon="code" href="/api-playground/overview" horizontal>
+<Card title="Set up API references" icon="code" href="/api-playground/overview" horizontal>
   Create interactive API references with OpenAPI and AsyncAPI specifications.
 </Card>