diff --git a/packages/docs/README.md b/packages/docs/README.md index 055c983ad..17956df32 100644 --- a/packages/docs/README.md +++ b/packages/docs/README.md @@ -40,4 +40,5 @@ Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/sett - If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. ### Resources + - [Mintlify documentation](https://mintlify.com/docs) diff --git a/packages/docs/ai-tools/claude-code.mdx b/packages/docs/ai-tools/claude-code.mdx index bdc4e04b5..4039c6e0e 100644 --- a/packages/docs/ai-tools/claude-code.mdx +++ b/packages/docs/ai-tools/claude-code.mdx @@ -14,8 +14,8 @@ Claude Code is Anthropic's official CLI tool. This guide will help you set up Cl 1. Install Claude Code globally: - ```bash - npm install -g @anthropic-ai/claude-code +```bash +npm install -g @anthropic-ai/claude-code ``` 2. Navigate to your docs directory. @@ -26,20 +26,23 @@ Claude Code is Anthropic's official CLI tool. This guide will help you set up Cl Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards: -````markdown +```markdown # 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 @@ -48,10 +51,12 @@ Create a `CLAUDE.md` file at the root of your documentation repository to train - 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 @@ -62,6 +67,7 @@ Create a `CLAUDE.md` file at the root of your documentation repository to train - 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 @@ -69,8 +75,9 @@ Create a `CLAUDE.md` file at the root of your documentation repository to train - 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 -```` +``` diff --git a/packages/docs/ai-tools/cursor.mdx b/packages/docs/ai-tools/cursor.mdx index fbb77616e..d05882919 100644 --- a/packages/docs/ai-tools/cursor.mdx +++ b/packages/docs/ai-tools/cursor.mdx @@ -99,12 +99,12 @@ Example of a single code block: ```javascript config.js const apiConfig = { - baseURL: 'https://api.example.com', + baseURL: "https://api.example.com", timeout: 5000, headers: { - 'Authorization': `Bearer ${process.env.API_TOKEN}` - } -}; + Authorization: `Bearer ${process.env.API_TOKEN}`, + }, +} ``` #### Code group with multiple languages @@ -120,7 +120,7 @@ const response = await fetch('/api/endpoint', { ```python Python import requests -response = requests.get('/api/endpoint', +response = requests.get('/api/endpoint', headers={'Authorization': f'Bearer {api_key}'}) ``` @@ -128,6 +128,7 @@ response = requests.get('/api/endpoint', curl -X GET '/api/endpoint' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` + #### Request/response examples @@ -328,10 +329,11 @@ Wrap all images in frames: Use the HTML video element for self-hosted video content: +controls +className="w-full aspect-video rounded-xl" +src="link-to-your-video.com" + +> Embed YouTube videos using iframe elements: @@ -362,9 +364,10 @@ Use updates for changelogs: - Improved error messages with actionable suggestions ## Bug fixes + - Fixed pagination issue with large datasets - Resolved authentication timeout problems - + ## Required page structure diff --git a/packages/docs/ai-tools/windsurf.mdx b/packages/docs/ai-tools/windsurf.mdx index fce12bfd1..310c81d5f 100644 --- a/packages/docs/ai-tools/windsurf.mdx +++ b/packages/docs/ai-tools/windsurf.mdx @@ -23,7 +23,7 @@ Create `.windsurf/rules.md` in your project root: ## Project context - This is a documentation project on the Mintlify platform -- We use MDX files with YAML frontmatter +- We use MDX files with YAML frontmatter - Navigation is configured in `docs.json` - We follow technical writing best practices @@ -53,7 +53,7 @@ description: "Concise description for SEO and navigation" - `` for helpful supplementary information - `` for important cautions and breaking changes -- `` for best practices and expert advice +- `` for best practices and expert advice - `` for neutral contextual information - `` for success confirmations @@ -80,7 +80,7 @@ description: "Concise description for SEO and navigation" ## API documentation requirements -- Document all parameters with `` +- Document all parameters with `` - Show response structure with `` - Include both success and error examples - Use `` for nested object properties diff --git a/packages/docs/api-reference/endpoint/create.mdx b/packages/docs/api-reference/endpoint/create.mdx index 5689f1b65..f09fb6411 100644 --- a/packages/docs/api-reference/endpoint/create.mdx +++ b/packages/docs/api-reference/endpoint/create.mdx @@ -1,4 +1,4 @@ --- -title: 'Create Plant' -openapi: 'POST /plants' +title: "Create Plant" +openapi: "POST /plants" --- diff --git a/packages/docs/api-reference/endpoint/delete.mdx b/packages/docs/api-reference/endpoint/delete.mdx index 657dfc871..db46bde6e 100644 --- a/packages/docs/api-reference/endpoint/delete.mdx +++ b/packages/docs/api-reference/endpoint/delete.mdx @@ -1,4 +1,4 @@ --- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' +title: "Delete Plant" +openapi: "DELETE /plants/{id}" --- diff --git a/packages/docs/api-reference/endpoint/get.mdx b/packages/docs/api-reference/endpoint/get.mdx index 56aa09ec1..f7c31f092 100644 --- a/packages/docs/api-reference/endpoint/get.mdx +++ b/packages/docs/api-reference/endpoint/get.mdx @@ -1,4 +1,4 @@ --- -title: 'Get Plants' -openapi: 'GET /plants' +title: "Get Plants" +openapi: "GET /plants" --- diff --git a/packages/docs/api-reference/endpoint/webhook.mdx b/packages/docs/api-reference/endpoint/webhook.mdx index 329134020..e80fc67eb 100644 --- a/packages/docs/api-reference/endpoint/webhook.mdx +++ b/packages/docs/api-reference/endpoint/webhook.mdx @@ -1,4 +1,4 @@ --- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' +title: "New Plant" +openapi: "WEBHOOK /plant/webhook" --- diff --git a/packages/docs/api-reference/introduction.mdx b/packages/docs/api-reference/introduction.mdx index c835b78b5..150f32e75 100644 --- a/packages/docs/api-reference/introduction.mdx +++ b/packages/docs/api-reference/introduction.mdx @@ -1,11 +1,11 @@ --- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' +title: "Introduction" +description: "Example section for showcasing API endpoints" --- - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. + If you're not looking to build API reference documentation, you can delete this section by removing the api-reference + folder. ## Welcome diff --git a/packages/docs/development.mdx b/packages/docs/development.mdx index ac633bad1..432ef80e4 100644 --- a/packages/docs/development.mdx +++ b/packages/docs/development.mdx @@ -1,13 +1,9 @@ --- -title: 'Development' -description: 'Preview changes locally to update your docs' +title: "Development" +description: "Preview changes locally to update your docs" --- - - **Prerequisites**: - - Node.js version 19 or higher - - A docs repository with a `docs.json` file - +**Prerequisites**: - Node.js version 19 or higher - A docs repository with a `docs.json` file Follow these steps to install and run Mintlify on your operating system. @@ -17,6 +13,7 @@ Follow these steps to install and run Mintlify on your operating system. ```bash npm i -g mint ``` + @@ -67,7 +64,11 @@ mint broken-links If the deployment is successful, you should see the following: - Screenshot of a deployment confirmation message that says All checks have passed. + Screenshot of a deployment confirmation message that says All checks have passed. ## Code formatting @@ -83,6 +84,7 @@ We suggest using extensions on your IDE to recognize and format MDX. If you're a 1. Remove the currently-installed version of the CLI: `npm remove -g mint` 2. Upgrade to Node v19 or higher. 3. Reinstall the CLI: `npm i -g mint` + diff --git a/packages/docs/docs.json b/packages/docs/docs.json index 7ff872c13..f4dda556d 100644 --- a/packages/docs/docs.json +++ b/packages/docs/docs.json @@ -15,35 +15,19 @@ "groups": [ { "group": "Getting started", - "pages": [ - "index", - "quickstart", - "development" - ] + "pages": ["index", "quickstart", "development"] }, { "group": "Customization", - "pages": [ - "essentials/settings", - "essentials/navigation" - ] + "pages": ["essentials/settings", "essentials/navigation"] }, { "group": "Writing content", - "pages": [ - "essentials/markdown", - "essentials/code", - "essentials/images", - "essentials/reusable-snippets" - ] + "pages": ["essentials/markdown", "essentials/code", "essentials/images", "essentials/reusable-snippets"] }, { "group": "AI tools", - "pages": [ - "ai-tools/cursor", - "ai-tools/claude-code", - "ai-tools/windsurf" - ] + "pages": ["ai-tools/cursor", "ai-tools/claude-code", "ai-tools/windsurf"] } ] }, @@ -52,9 +36,7 @@ "groups": [ { "group": "API documentation", - "pages": [ - "api-reference/introduction" - ] + "pages": ["api-reference/introduction"] }, { "group": "Endpoint examples", @@ -101,16 +83,7 @@ } }, "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity", - "mcp", - "cursor", - "vscode" - ] + "options": ["copy", "view", "chatgpt", "claude", "perplexity", "mcp", "cursor", "vscode"] }, "footer": { "socials": { diff --git a/packages/docs/essentials/code.mdx b/packages/docs/essentials/code.mdx index ae2abbfec..7a0465447 100644 --- a/packages/docs/essentials/code.mdx +++ b/packages/docs/essentials/code.mdx @@ -1,7 +1,7 @@ --- -title: 'Code blocks' -description: 'Display inline code and code blocks' -icon: 'code' +title: "Code blocks" +description: "Display inline code and code blocks" +icon: "code" --- ## Inline code diff --git a/packages/docs/essentials/images.mdx b/packages/docs/essentials/images.mdx index 1144eb2cc..f2a10d253 100644 --- a/packages/docs/essentials/images.mdx +++ b/packages/docs/essentials/images.mdx @@ -1,13 +1,10 @@ --- -title: 'Images and embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' +title: "Images and embeds" +description: "Add image, video, and other HTML elements" +icon: "image" --- - + ## Image @@ -39,7 +36,7 @@ To get more customizability with images, you can also use [embeds](/writing-cont frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen - style={{ width: '100%', borderRadius: '0.5rem' }} + style={{ width: "100%", borderRadius: "0.5rem" }} >
diff --git a/packages/docs/essentials/markdown.mdx b/packages/docs/essentials/markdown.mdx index a45c1d569..0ca5b8250 100644 --- a/packages/docs/essentials/markdown.mdx +++ b/packages/docs/essentials/markdown.mdx @@ -1,7 +1,7 @@ --- -title: 'Markdown syntax' -description: 'Text, title, and styling in standard markdown' -icon: 'text-size' +title: "Markdown syntax" +description: "Text, title, and styling in standard markdown" +icon: "text-size" --- ## Titles diff --git a/packages/docs/essentials/navigation.mdx b/packages/docs/essentials/navigation.mdx index 60adeff23..a6a309004 100644 --- a/packages/docs/essentials/navigation.mdx +++ b/packages/docs/essentials/navigation.mdx @@ -1,7 +1,7 @@ --- -title: 'Navigation' -description: 'The navigation field in docs.json defines the pages that go in the navigation menu' -icon: 'map' +title: "Navigation" +description: "The navigation field in docs.json defines the pages that go in the navigation menu" +icon: "map" --- The navigation menu is the list of links on every website. diff --git a/packages/docs/essentials/reusable-snippets.mdx b/packages/docs/essentials/reusable-snippets.mdx index 376e27bd9..a26ab89a3 100644 --- a/packages/docs/essentials/reusable-snippets.mdx +++ b/packages/docs/essentials/reusable-snippets.mdx @@ -4,7 +4,7 @@ description: "Reusable, custom snippets to keep content in sync" icon: "recycle" --- -import SnippetIntro from '/snippets/snippet-intro.mdx'; +import SnippetIntro from "/snippets/snippet-intro.mdx" @@ -13,9 +13,8 @@ import SnippetIntro from '/snippets/snippet-intro.mdx'; **Pre-condition**: You must create your snippet file in the `snippets` directory. - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a + Any page in the `snippets` directory will be treated as a snippet and will not be rendered into a standalone page. If + you want to create a standalone page from the snippet, import the snippet into another file and call it as a component. @@ -31,8 +30,7 @@ day is {word}. ``` - The content that you want to reuse must be inside the `snippets` directory in - order for the import to work. + The content that you want to reuse must be inside the `snippets` directory in order for the import to work. 2. Import the snippet into your destination file. @@ -43,7 +41,7 @@ title: My title description: My Description --- -import MySnippet from '/snippets/path/to/my-snippet.mdx'; +import MySnippet from "/snippets/path/to/my-snippet.mdx" ## Header @@ -57,9 +55,11 @@ Lorem impsum dolor sit amet. 1. Export a variable from your snippet file: ```mdx snippets/path/to/custom-variables.mdx -export const myName = 'my name'; +export const myName = "my name" -export const myObject = { fruit: 'strawberries' }; +export const myObject = { fruit: "strawberries" } + +; ``` 2. Import the snippet from your destination file and use the variable: @@ -70,7 +70,7 @@ title: My title description: My Description --- -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; +import { myName, myObject } from "/snippets/path/to/custom-variables.mdx" Hello, my name is {myName} and I like {myObject.fruit}. ``` @@ -86,12 +86,14 @@ export const MyComponent = ({ title }) => (

{title}

... snippet content ...

-); +) + +; ``` - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. + MDX does not compile inside the body of an arrow function. Stick to HTML syntax when you can or use a default export + if you need to use MDX. 2. Import the snippet into your destination file and pass in the props @@ -102,9 +104,9 @@ title: My title description: My Description --- -import { MyComponent } from '/snippets/custom-component.mdx'; +import { MyComponent } from "/snippets/custom-component.mdx" Lorem ipsum dolor sit amet. - + ``` diff --git a/packages/docs/essentials/settings.mdx b/packages/docs/essentials/settings.mdx index 884de13a4..7aa44ce1e 100644 --- a/packages/docs/essentials/settings.mdx +++ b/packages/docs/essentials/settings.mdx @@ -1,7 +1,7 @@ --- -title: 'Global Settings' -description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file' -icon: 'gear' +title: "Global Settings" +description: "Mintlify gives you complete control over the look and feel of your documentation using the docs.json file" +icon: "gear" --- Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below. @@ -57,12 +57,11 @@ Example: `mintlify` Hex color codes for your global theme - The primary color. Used for most often for highlighted content, section - headers, accents, in light mode + The primary color. Used for most often for highlighted content, section headers, accents, in light mode - The primary color for dark mode. Used for most often for highlighted - content, section headers, accents, in dark mode + The primary color for dark mode. Used for most often for highlighted content, section headers, accents, in dark + mode The primary color for important buttons @@ -114,8 +113,8 @@ Example: `mintlify` - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. + Array of version names. Only use this if you want to show different versions of docs with a dropdown in the navigation + bar. @@ -172,8 +171,8 @@ Example: `mintlify` The name of the tab label. - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. + The start of the URL that marks what pages go in the tab. Generally, this is the name of the folder you put your + pages in. @@ -313,6 +312,6 @@ Example: `mintlify` - A background image to be displayed behind every page. See example with - [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). + A background image to be displayed behind every page. See example with [Infisical](https://infisical.com/docs) and + [FRPC](https://frpc.io). diff --git a/packages/docs/index.mdx b/packages/docs/index.mdx index 15c23fb6c..19a09f890 100644 --- a/packages/docs/index.mdx +++ b/packages/docs/index.mdx @@ -7,12 +7,7 @@ description: "Welcome to the new home for your documentation" Get your documentation site up and running in minutes. - + Follow our three step quickstart guide. @@ -21,32 +16,16 @@ Get your documentation site up and running in minutes. Design a docs site that looks great and empowers your users. - + Edit your docs locally and preview them in real time. - + Customize the design and colors of your site to match your brand. - + Organize your docs to help users find what they need and succeed with your product. - + Auto-generate API documentation from OpenAPI specifications. @@ -56,42 +35,22 @@ Design a docs site that looks great and empowers your users. Everything you need to create world-class documentation. - + Use MDX to style your docs pages. - + Add sample code to demonstrate how to use your product. - + Display images and other media. - + Write once and reuse across your docs. ## Need inspiration? - + Browse our showcase of exceptional documentation sites. diff --git a/packages/docs/quickstart.mdx b/packages/docs/quickstart.mdx index c711458ba..52243fba6 100644 --- a/packages/docs/quickstart.mdx +++ b/packages/docs/quickstart.mdx @@ -11,15 +11,15 @@ Get your documentation site running locally and make your first customization. - During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com). - - To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs. + During the onboarding process, you created a GitHub repository with your docs content if you didn't already have + one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com). To clone the + repository locally so that you can make and preview changes to your docs, follow the [Cloning a + repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide + in the GitHub docs. - 1. Install the Mintlify CLI: `npm i -g mint` - 2. Navigate to your docs directory and run: `mint dev` - 3. Open `http://localhost:3000` to see your docs live! - + 1. Install the Mintlify CLI: `npm i -g mint` 2. Navigate to your docs directory and run: `mint dev` 3. Open + `http://localhost:3000` to see your docs live! Your preview updates automatically as you edit files. @@ -41,14 +41,14 @@ Get your documentation site running locally and make your first customization. 4. Save and see your changes instantly at `http://localhost:3000`. Try changing the primary color to see an immediate difference! + ### Step 3: Go live - 1. Commit and push your changes. - 2. Your docs will update and be live in moments! + 1. Commit and push your changes. 2. Your docs will update and be live in moments! ## Next steps @@ -76,5 +76,6 @@ Now that you have your docs running, explore these key features: - **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community). + **Need help?** See our [full documentation](https://mintlify.com/docs) or join our + [community](https://mintlify.com/community).