From 9406985331a605ec051ba1847bb3c6d61cb9a441 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 10:08:03 -0700 Subject: [PATCH 1/7] add Claude Code page --- docs.json | 1 + guides/claude-code.mdx | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100644 guides/claude-code.mdx diff --git a/docs.json b/docs.json index 423bca30c..9f5bd19f2 100644 --- a/docs.json +++ b/docs.json @@ -110,6 +110,7 @@ "guides/analytics", "guides/assistant", "mcp", + "guides/claude-code", "guides/cursor", "translations", "react-components", diff --git a/guides/claude-code.mdx b/guides/claude-code.mdx new file mode 100644 index 000000000..756802726 --- /dev/null +++ b/guides/claude-code.mdx @@ -0,0 +1,21 @@ +--- +title: "Claude Code" +description: "Configure Claude Code to help write, review, and update docs" +icon: "asterisk" +--- + +Claude Code is an agentic command line tool that lets you delegate documentation tasks from your terminal. You can create workflows to create, maintain, and review your docs. + +Claude Code can be used immediately after installation, but becomes more powerful when you configure it to work with your docs. + +## Prerequisites + +- Claude Code API key + +## Set up + +## Use cases + +Claude Code is a tool that allows you to use Claude to write code. + +## Examples \ No newline at end of file From d1b85e6d12e1344a42cdf7b018985a9f4e0a1be8 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 10:08:10 -0700 Subject: [PATCH 2/7] add CLAUDE.md file --- .claude/CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .claude/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 000000000..0f66fa060 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,53 @@ +# Documentation project context + +## Project overview +This is a Mintlify documentation site built with MDX files and configured +via docs.json. The site follows Mintlify's documentation framework with +structured navigation, components, and theming. + +## File structure and conventions +- **Main config**: `docs.json` - contains navigation, theme settings, and +site configuration +- **Content**: All documentation is in `.mdx` files with frontmatter +- **Structure**: Organized in folders matching the navigation structure +- **Images**: Stored in `/images/` directory with light/dark variants +- **Components**: Reusable components documented in `/components/` folder + +## Documentation standards +- Use MDX format with YAML frontmatter containing: title, description, +icon +- Follow existing navigation structure defined in docs.json +- Use Mintlify components: ``, ``, ``, ``, +``, `` +- Include light/dark mode image variants when applicable +- Use `` component for image containers +- Code blocks should specify language for syntax highlighting + +## Writing style +- Clear, concise technical writing +- Step-by-step guides with numbered lists +- Use callouts for important information +- Include prerequisites sections where needed +- Provide code examples and configuration snippets + +## Common components +- ``, ``, ``, ``, ``, `` for +callouts +- `` for image containers +- `` for code examples +- Custom React components (like HeroCard in index.mdx) + +## Key areas +- Getting started guides (quickstart, installation) +- API documentation and playground setup +- Component documentation +- Integration guides +- Settings and configuration +- Authentication and personalization + +## When editing existing files +- Maintain consistent frontmatter structure +- Follow existing component usage patterns +- Keep navigation structure aligned with docs.json +- Use appropriate callout types for different message types +- Include relevant icons in frontmatter From dfa112dab787badab92d8a7f72e1bb5d626f4828 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 10:33:38 -0700 Subject: [PATCH 3/7] revise CLAUDE.md --- .claude/CLAUDE.md | 80 ++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 46 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 0f66fa060..3045f6373 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,53 +1,41 @@ -# Documentation project context +# Mintlify documentation -## Project overview -This is a Mintlify documentation site built with MDX files and configured -via docs.json. The site follows Mintlify's documentation framework with -structured navigation, components, and theming. +## Project context +- Official documentation site for Mintlify platform +- Format: MDX files with YAML frontmatter +- Config: docs.json for navigation, theme, settings +- Images: /images/ directory with light/dark variants -## File structure and conventions -- **Main config**: `docs.json` - contains navigation, theme settings, and -site configuration -- **Content**: All documentation is in `.mdx` files with frontmatter -- **Structure**: Organized in folders matching the navigation structure -- **Images**: Stored in `/images/` directory with light/dark variants -- **Components**: Reusable components documented in `/components/` folder +## Content strategy +- Use MCP search before writing new content +- Check existing patterns for consistency +- Cross-link to related information when it helps users accomplish tasks +- Maintain examples that work for all Mintlify users -## Documentation standards -- Use MDX format with YAML frontmatter containing: title, description, -icon -- Follow existing navigation structure defined in docs.json -- Use Mintlify components: ``, ``, ``, ``, -``, `` -- Include light/dark mode image variants when applicable -- Use `` component for image containers -- Code blocks should specify language for syntax highlighting +## Frontmatter requirements +- title: Clear, descriptive page title +- description: Concise summary for SEO/navigation +- icon: Appropriate icon matching content type -## Writing style -- Clear, concise technical writing -- Step-by-step guides with numbered lists -- Use callouts for important information -- Include prerequisites sections where needed -- Provide code examples and configuration snippets +## Writing standards +- Second-person voice ("you") +- Prerequisites at start of procedural content +- Test all code examples +- Include both basic and advanced use cases +- Add troubleshooting for complex features -## Common components -- ``, ``, ``, ``, ``, `` for -callouts -- `` for image containers -- `` for code examples -- Custom React components (like HeroCard in index.mdx) +## Components (quick reference) +- Callouts: ``, ``, ``, ``, ``, `` +- Layout: ``, ``, ``, `` -## Key areas -- Getting started guides (quickstart, installation) -- API documentation and playground setup -- Component documentation -- Integration guides -- Settings and configuration -- Authentication and personalization +## File standards +- Language tags on all code blocks +- Alt text on all images +- Relative paths for internal links +- Light/dark image variants where applicable -## When editing existing files -- Maintain consistent frontmatter structure -- Follow existing component usage patterns -- Keep navigation structure aligned with docs.json -- Use appropriate callout types for different message types -- Include relevant icons in frontmatter +## Do Not +- Skip frontmatter on any MDX file +- Use absolute URLs for internal links +- Include untested code examples +- Break backward compatibility without migration notes From 56b861d567c0914f36eb47d0b848ebf48afb9ffc Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 14:04:44 -0700 Subject: [PATCH 4/7] different CLAUDE.md approach --- .claude/CLAUDE.md | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 3045f6373..4749ee6a4 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,41 +1,46 @@ # Mintlify documentation +## 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 -- Official documentation site for Mintlify platform - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings -- Images: /images/ directory with light/dark variants +- Components: Mintlify components ## Content strategy -- Use MCP search before writing new content +- 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 -- Cross-link to related information when it helps users accomplish tasks -- Maintain examples that work for all Mintlify users +- Start by making the smallest reasonable changes -## Frontmatter requirements +## Frontmatter requirements for pages - title: Clear, descriptive page title - description: Concise summary for SEO/navigation -- icon: Appropriate icon matching content type ## Writing standards - Second-person voice ("you") - Prerequisites at start of procedural content -- Test all code examples +- Test all code examples before publishing +- Match style and formatting of existing pages - Include both basic and advanced use cases -- Add troubleshooting for complex features - -## Components (quick reference) -- Callouts: ``, ``, ``, ``, ``, `` -- Layout: ``, ``, ``, `` - -## File standards - Language tags on all code blocks - Alt text on all images - Relative paths for internal links -- Light/dark image variants where applicable -## Do Not +## 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 -- Break backward compatibility without migration notes +- Make assumptions - always ask for clarification \ No newline at end of file From 8bf920a17b73fc6e46363dbc33f42c06a0f145ed Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 15:19:23 -0700 Subject: [PATCH 5/7] add info on using Claude Code to maintain docs --- guides/claude-code.mdx | 128 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 119 insertions(+), 9 deletions(-) diff --git a/guides/claude-code.mdx b/guides/claude-code.mdx index 756802726..b79321dfb 100644 --- a/guides/claude-code.mdx +++ b/guides/claude-code.mdx @@ -1,21 +1,131 @@ --- title: "Claude Code" -description: "Configure Claude Code to help write, review, and update docs" +description: "Configure Claude Code to help write, review, and update your docs" icon: "asterisk" --- -Claude Code is an agentic command line tool that lets you delegate documentation tasks from your terminal. You can create workflows to create, maintain, and review your docs. +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. -Claude Code can be used immediately after installation, but becomes more powerful when you configure it to work with your docs. +You can train Claude Code to understand your documentation standards and workflows by adding a `CLAUDE.md` file to your project and refining it over time. -## Prerequisites +## Getting started -- Claude Code API key +**Prerequisites:** +- Active Claude subscription (Pro, Max, or API access) +- Node.js v19+ installed -## Set up +**Setup:** +1. Install Claude Code: + ```bash + npm install -g @anthropic-ai/claude-code + ``` +2. Navigate to your docs directory. +3. (Optional) Add the `CLAUDE.md` file below to your project. +4. Run `claude` to start. -## Use cases +## CLAUDE.md template -Claude Code is a tool that allows you to use Claude to write code. +Save a `CLAUDE.md` file at the root of your docs directory to help Claude Code understand your project. This file trains Claude Code on your documentation standards, preferences, and workflows. See [Manage Claude's memory](https://docs.anthropic.com/en/docs/claude-code/memory) in the Anthropic docs for more information. -## Examples \ No newline at end of file +Copy this example template or make changes for your docs specifications: + +```mdx +# Mintlify documentation + +## 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 + +## 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 +``` + +## Sample prompts + +Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs. + +### Convert notes to polished docs +Turn rough drafts into proper `MDX` with components and frontmatter. + +**Example prompt:** +```text wrap +Convert this text into a properly formatted MDX page: [paste your text here] +``` + +### Review docs for consistency +Get suggestions to improve style, formatting, and component usage. + +**Example prompt:** +```text wrap +Review the files in docs/ and suggest improvements for consistency and clarity +``` + +### Update docs when features change +Keep documentation current when your product evolves. + +**Example prompt:** +```text wrap +Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples +``` + +### Generate comprehensive code examples +Create multi-language examples with error handling. + +**Example prompt:** +```text wrap +Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling +``` + +## Extending Claude Code + +Beyond manually prompting Claude Code, you can integrate it with your existing workflows. + +### Automation with GitHub Actions +Run Claude Code automatically when code changes to keep docs up to date. You can trigger documentation reviews on pull requests or update examples when API changes are detected. + +### Multi-instance workflows +Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss. + +### Team collaboration +Share your refined `CLAUDE.md` file with your team to ensure documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process. + +### Custom commands +Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team. From aaf0bba4de156a3fbafc79b4dcf623ca33908166 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 15:21:47 -0700 Subject: [PATCH 6/7] remove node prereq since redundant with Mintlify --- guides/claude-code.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/claude-code.mdx b/guides/claude-code.mdx index b79321dfb..83e101f70 100644 --- a/guides/claude-code.mdx +++ b/guides/claude-code.mdx @@ -12,7 +12,6 @@ You can train Claude Code to understand your documentation standards and workflo **Prerequisites:** - Active Claude subscription (Pro, Max, or API access) -- Node.js v19+ installed **Setup:** 1. Install Claude Code: From 1b5b942ed1e765fcdddc4c5a1a68de071c612dd5 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 15:27:26 -0700 Subject: [PATCH 7/7] =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- guides/claude-code.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/claude-code.mdx b/guides/claude-code.mdx index 83e101f70..e0b53bc55 100644 --- a/guides/claude-code.mdx +++ b/guides/claude-code.mdx @@ -82,7 +82,7 @@ Copy this example template or make changes for your docs specifications: Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs. ### Convert notes to polished docs -Turn rough drafts into proper `MDX` with components and frontmatter. +Turn rough drafts into proper Markdown pages with components and frontmatter. **Example prompt:** ```text wrap @@ -124,7 +124,7 @@ Run Claude Code automatically when code changes to keep docs up to date. You can Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss. ### Team collaboration -Share your refined `CLAUDE.md` file with your team to ensure documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process. +Share your refined `CLAUDE.md` file with your team to ensure consistent documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process. ### Custom commands Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team.