Skip to content

Update MCP Docs with Mintlify guidelines #2382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+59 −0
Open

Update MCP Docs with Mintlify guidelines #2382

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Mintlify documentation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

⚠️ Potential issue

Add required YAML frontmatter and avoid duplicate H1

This page prescribes frontmatter but doesn’t include any. Mintlify expects frontmatter for proper rendering and navigation. Replace the top-level H1 with frontmatter to avoid duplicate titles.

+---
+title: Mintlify documentation guidelines
+description: Standards and practices for writing and maintaining Mintlify-based docs in this repository.
+---
-
-# Mintlify documentation
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Mintlify documentation
---
title: Mintlify documentation guidelines
description: Standards and practices for writing and maintaining Mintlify-based docs in this repository.
---
🤖 Prompt for AI Agents 
In docs/CLAUDE.md around lines 1 to 1, the file is missing the required YAML
frontmatter and currently starts with a top-level H1; remove that H1 and add
YAML frontmatter at the top (between --- markers) specifying at minimum a title
(e.g., title: "Mintlify documentation") and any navigation or metadata fields
your site requires, then delete the duplicate H1 header so the page renders
correctly and avoids a duplicated title.


Our docs are written using Mintlify. Please refer to the [Mintlify documentation](https://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their components. Make sure to use their components where possible, especially for documenting parameters and responses using their ParamField, ResponseField, Expandable, etc. Use CodeGroup when you want to show multiple code editors side by side. Use Callout when you want to call out important information. Accordions are great for showing more detail but without the need to scroll. The Step component is great for showing a list of steps.There are also Tabs, Tooltips, etc.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

❓ Verification inconclusive

Fix incorrect link, tone, and run-on sentence; break into scannable bullets

The Mintlify link appears incorrect, the tone (“amazing”) is informal, and this is a very long line with a spacing error (“steps.There”). Refactor into bullets and tighten wording.

-Our docs are written using Mintlify. Please refer to the [Mintlify documentation](https://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their components. Make sure to use their components where possible, especially for documenting parameters and responses using their ParamField, ResponseField, Expandable, etc. Use CodeGroup when you want to show multiple code editors side by side. Use Callout when you want to call out important information. Accordions are great for showing more detail but without the need to scroll. The Step component is great for showing a list of steps.There are also Tabs, Tooltips, etc.
+Our docs use Mintlify. Refer to the official Mintlify docs for component usage and authoring guidelines:
+
+- Prefer Mintlify components over raw HTML where possible.
+- For parameters and responses, use ParamField and ResponseField. For collapsible details, use Expandable.
+- Use CodeGroup to present multiple language examples side by side.
+- Use Callout to highlight important information.
+- Use Accordions to reveal advanced or optional details without adding scroll.
+- Use Step for step-by-step procedures.
+- Tabs and Tooltips are also available when appropriate.
+
+See: https://mintlify.com/docs

Fix incorrect Mintlify link, informal tone, and run-on sentence; break into scannable bullets

Please update the Mintlify section in docs/CLAUDE.md to:

  • Use the correct, current documentation URL
  • Remove informal language (“amazing”)
  • Insert the missing space after “steps.”
  • Break the content into clear, scannable bullets

Location:

  • docs/CLAUDE.md: line 3

Suggested diff:

-Our docs are written using Mintlify. Please refer to the [Mintlify documentation](https://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their components. Make sure to use their components where possible, especially for documenting parameters and responses using their ParamField, ResponseField, Expandable, etc. Use CodeGroup when you want to show multiple code editors side by side. Use Callout when you want to call out important information. Accordions are great for showing more detail but without the need to scroll. The Step component is great for showing a list of steps.There are also Tabs, Tooltips, etc.
+Our docs use Mintlify. Refer to the official Mintlify documentation for component usage and authoring guidelines:
+
+- Prefer Mintlify components over raw HTML where possible.
+- Use ParamField and ResponseField to document parameters and responses.
+- Use Expandable for collapsible content.
+- Use CodeGroup to present multiple language examples side by side.
+- Use Callout to highlight important information.
+- Use Accordions to reveal advanced or optional details without adding scroll.
+- Use Step for step-by-step procedures.
+- Tabs and Tooltips are also available when appropriate.
+
+See: https://docs.mintlify.com
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Our docs are written using Mintlify. Please refer to the [Mintlify documentation](https://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their components. Make sure to use their components where possible, especially for documenting parameters and responses using their ParamField, ResponseField, Expandable, etc. Use CodeGroup when you want to show multiple code editors side by side. Use Callout when you want to call out important information. Accordions are great for showing more detail but without the need to scroll. The Step component is great for showing a list of steps.There are also Tabs, Tooltips, etc.
Our docs use Mintlify. Refer to the official Mintlify documentation for component usage and authoring guidelines:
- Prefer Mintlify components over raw HTML where possible.
- Use ParamField and ResponseField to document parameters and responses.
- Use Expandable for collapsible content.
- Use CodeGroup to present multiple language examples side by side.
- Use Callout to highlight important information.
- Use Accordions to reveal advanced or optional details without adding scroll.
- Use Step for step-by-step procedures.
- Tabs and Tooltips are also available when appropriate.
See: https://docs.mintlify.com
🧰 Tools
🪛 LanguageTool

[style] ~3-~3: Consider using a more formal and expressive alternative to ‘amazing’.
Context: ...://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their c...

(AWESOME)

[style] ~3-~3: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...tors side by side. Use Callout when you want to call out important information. Accordi...

(REP_WANT_TO_VB)

🤖 Prompt for AI Agents 
In docs/CLAUDE.md around line 3, the Mintlify section uses an incorrect link,
informal wording, a missing space after "steps.", and is a run-on sentence;
replace the URL with the correct documentation URL (https://docs.mintlify.com),
remove informal language like "amazing", add the missing space after "steps.",
and reformat the paragraph into short, scannable bullet points that mention
using Mintlify components (ParamField, ResponseField, Expandable, CodeGroup,
Callout, Accordions, Step, Tabs, Tooltips) where appropriate.


## Working relationship

- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information

## Project context

- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components

## Content strategy

- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability of information
- Make content evergreen when possible
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes

## docs.json

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation

## Frontmatter requirements for pages

- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation

## Writing standards

- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links

## Git workflow

- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks

## Do not

- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification