diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 213dd1250..6f2f6408c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -34,6 +34,41 @@ - Use broadly applicable examples rather than overly specific business cases - Lead with context when helpful - explain what something is before diving into implementation details +### Style preferences (learned from content refresh project) +#### Headings and formatting +- Use sentence case for all headings ("Getting started", not "Getting Started") +- Use "Properties" instead of "Props" for component documentation +- Use sentence case for code block titles ("Expandable example", not "Expandable Example") + +#### Component introductions +- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..." +- Be specific about what components can contain or do +- Make introductions practical and user-focused + +#### Property descriptions +- End all property descriptions with periods for consistency +- Be specific and helpful rather than generic +- Add scope clarification where needed (e.g., "For Font Awesome icons only:") +- Use proper technical terminology ("boolean" not "bool") + +#### Language and tone +- Prefer active voice and direct language +- Remove unnecessary words while maintaining clarity +- Use "you complete" over "completing" for more direct communication +- Break complex instructions into clear numbered steps +- Make language more precise and contextual + +#### Code examples +- Keep examples simple and practical +- Use consistent formatting and naming +- Provide clear, actionable examples rather than showing multiple options when one will do + +#### Content organization +- Structure content in the order users need it +- Combine related information to reduce redundancy +- Use specific links (direct to relevant pages rather than generic dashboards) +- Put most commonly needed information first + ## Git workflow - NEVER use --no-verify when committing - Ask how to handle uncommitted changes before starting diff --git a/components/cards.mdx b/components/cards.mdx index 7ee626e7f..f724c5452 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -1,50 +1,66 @@ --- title: "Cards" -description: "Highlight main points or links with customizable icons" -icon: 'square-mouse-pointer' +description: "Highlight main points or links with customizable layouts and icons" +icon: "square-mouse-pointer" --- - +Use cards to create visual containers for content. Cards are flexible containers that can include text, icons, images, and links. + +## Basic card + + This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. - - ```mdx Card Example - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. - - ``` - -```mdx Image Card Example - - Here is an example of a card with an image +```mdx Card example + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Columns page. ``` - +## Card variations -## Horizontal card +Cards support several layout and styling options to fit different content needs. -Add a `horizontal` property to display cards horizontally. +### Horizontal layout - - Here is an example of a horizontal card +Add the `horizontal` property to display cards in a more compact, horizontal layout. + + + This is an example of a horizontal card. -## Image card +```mdx Horizontal card example + + This is an example of a horizontal card. + +``` + +### Image cards -Add an `img` property to display an image on the top of the card. +Add an `img` property to display an image at the top of the card. - - Here is an example of a card with an image + + This is an example of a card with an image. -## Link card +```mdx Image card example + + This is an example of a card with an image. + +``` -You can customize the CTA and whether or not to display the arrow on the card. By default, the arrow will only show for external links. +### Link cards with custom CTAs + +You can customize the call-to-action text and control whether an arrow appears. By default, arrows only show for external links. + + + This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page. + +```mdx Link card example - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. + This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page. - - - ```mdx Card Example - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. - - ``` - +``` ## Grouping cards -You can group cards in [columns](/components/columns). +Use the [Columns component](/components/columns) to organize multiple cards side by side. - + This is the first card. - + This is the second card. -## Props +```mdx Columns example + + + This is the first card. + + + This is the second card. + + +``` + +## Properties - The title of the card + The title displayed on the card - A [Font Awesome icon](https://fontawesome.com/icons), [Lucide - icon](https://lucide.dev/icons), or JSX compatible SVG code in `icon={}`. - - To generate JSX compatible SVG code: - + Icon to display on the card. Use a [Font Awesome icon](https://fontawesome.com/icons) name, [Lucide icon](https://lucide.dev/icons) name, or JSX-compatible SVG code wrapped in `icon={}`. + + For custom SVG icons: 1. Use the [SVGR converter](https://react-svgr.com/playground/). 2. Copy the code inside the `` tag. - 3. Paste the code into your card. Make sure to only copy and paste the code inside the `` tag. - 4. You may need to decrease the height and width to make the image fit. + 3. Paste the code into your card. + 4. Adjust height and width as needed. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` + Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, or `brands`. - The color of the icon as a hex code + Icon color as a hex code (e.g., `#FF6B6B`). - The url that clicking on the card would navigate the user to + URL to navigate to when the card is clicked. - Makes the card more compact and horizontal + Display the card in a compact horizontal layout. - The url or local path to an image to display on the top of the card + URL or local path to an image displayed at the top of the card. - Label for the action button + Custom text for the action button. - Enable or disable the link arrow icon + Show or hide the link arrow icon. diff --git a/components/expandables.mdx b/components/expandables.mdx index 431048ca0..45f8a91e6 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -1,9 +1,11 @@ --- title: "Expandables" -description: "Toggle to display nested properties." -icon: 'list-tree' +description: "Toggle to display nested properties" +icon: "list-tree" --- +Use expandables to show and hide nested content within response fields. Expandables are particularly useful for displaying complex object properties in API documentation. + @@ -18,9 +20,7 @@ icon: 'list-tree' - - -```mdx Expandable Example +```mdx Expandable example @@ -34,15 +34,12 @@ icon: 'list-tree' ``` - - -## Props +## Properties - The name of the object you are showing. Used to generate the "Show NAME" and - "Hide NAME" text. + The name of the object you are showing. - Set to true to show the component as open when the page loads. + Set to `true` for the expandable to open when the page loads diff --git a/components/fields.mdx b/components/fields.mdx index 99d0a2c14..7a06d6d1d 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -1,85 +1,69 @@ --- title: "Fields" description: "Set parameters for your API or SDK references" -icon: 'letter-text' +icon: "letter-text" --- -There are two types of fields: Parameter Fields and Response Fields. +Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields. -## Parameter Field +## Parameter field -A `ParamField` component is used to define the parameters for your APIs or SDKs. Adding a `ParamField` will automatically add an [API Playground](/api-playground/overview). +The `` component is used to define parameters for your APIs or SDKs. Adding a `ParamField` automatically adds an [API Playground](/api-playground/overview). An example of a parameter field - - -```mdx Path Example - +```mdx + An example of a parameter field ``` -```mdx Body Example - - The age of the user. Cannot be less than 0 - -``` - -```mdx Response Example - - A response field example - -``` - - - -### Props +### Properties - Whether it is a query, path, body, or header parameter followed by the name + Whether the parameter is a query, path, body, or header. Followed by the parameter name. - Expected type of the parameter's value + Expected type of the parameter's value. - Supports `number`, `string`, `bool`, `object`. + Supports `number`, `string`, `boolean`, `object`. - Arrays can be defined using the `[]` suffix. For example `string[]`. + Arrays can be defined using the `[]` suffix. For example, `string[]`. - Indicate whether the parameter is required + Indicate whether the parameter is required. - Indicate whether the parameter is deprecated + Indicate whether the parameter is deprecated. - Default value used by the server if the request does not provide a value + Default value used by the server if the request does not provide a value. - Value that will be used to initialize the playground + Value that will be used to initialize the playground. - Placeholder text for the input in the playground + Placeholder text for the input in the playground. - Description of the parameter (markdown enabled) + Description of the parameter (Markdown-enabled). -## Response Field +## Response field -The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something. +The `` component defines the return values of an API. - A response field example + An example of a response field ```mdx @@ -88,14 +72,14 @@ The `` component is designed to define the return values of an AP ``` -### Props +### Properties The name of the response value. - Expected type of the response value - this can be any arbitrary string. + Expected type of the response value. This can be any arbitrary string. @@ -103,17 +87,17 @@ The `` component is designed to define the return values of an AP - Show "required" beside the field name. + Indicate whether the response is required. - Whether a field is deprecated or not. + Whether a field is deprecated. - Labels that are shown before the name of the field + Labels that are shown before the name of the field. - Labels that are shown after the name of the field + Labels that are shown after the name of the field. diff --git a/components/icons.mdx b/components/icons.mdx index 22d041db0..d703d2858 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -4,40 +4,38 @@ description: "Use icons from popular icon libraries" icon: "flag" --- - +Use icons from Font Awesome, Lucide, URLs, or files in your project to enhance your documentation. - + -```mdx Icon Example +```mdx Icon example ``` - +## Inline icons -## Inline Icons +Icons are placed inline when used within a paragraph. -The icon will be placed inline when used in a paragraph. - -```markdown Inline Icon Example - The documentation you want, effortlessly. -``` + The documentation you want, effortlessly. +```markdown Inline icon example The documentation you want, effortlessly. +``` -### Props +## Properties A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons). + For [Font Awesome](https://fontawesome.com/icons) icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. - The color of the icon as a hex code (e.g., `#FF5733`) + The color of the icon as a hex code (for example, `#FF5733`). - The size of the icon in pixels - \ No newline at end of file + The size of the icon in pixels. + diff --git a/components/mermaid-diagrams.mdx b/components/mermaid-diagrams.mdx index 100fec13d..9cd507de0 100644 --- a/components/mermaid-diagrams.mdx +++ b/components/mermaid-diagrams.mdx @@ -1,12 +1,16 @@ --- -title: 'Mermaid' -description: 'Display diagrams using Mermaid' -icon: 'waypoints' +title: "Mermaid" +description: "Display diagrams using Mermaid" +icon: "waypoints" --- +[Mermaid](https://mermaid.js.org/) lets you build flowcharts, sequence diagrams, Gantt charts, and other diagrams using text and code. + +For a complete list of supported diagram types and syntax, see the [Mermaid documentation](https://mermaid.js.org/intro/). + -````mdx Mermaid Flowchart Example +````mdx Mermaid flowchart example ```mermaid flowchart LR subgraph subgraph1 @@ -29,8 +33,6 @@ icon: 'waypoints' -[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. - ```mermaid flowchart LR subgraph subgraph1 @@ -50,14 +52,12 @@ icon: 'waypoints' outside ---> top2 ``` -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). - -## Syntax for Mermaid diagrams +## Syntax -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. +To create a Mermaid diagram, write your diagram definition inside a Mermaid code block. ````mdx ```mermaid -// Your mermaid code block here +// Your mermaid diagram code here ``` ```` diff --git a/components/steps.mdx b/components/steps.mdx index fa0087db2..cd80b3fb8 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -1,10 +1,10 @@ --- -title: 'Steps' -description: 'Sequence content using the Steps component' -icon: 'list-todo' +title: "Steps" +description: "Sequence content using the Steps component" +icon: "list-todo" --- -Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. +Use steps to display a series of sequential actions or events. You can add as many steps as needed. @@ -18,9 +18,7 @@ Steps are the best way to display a series of actions of events to your users. Y - - -```mdx Steps Example +```mdx Steps example These are instructions or content that only pertain to the first step. @@ -34,30 +32,28 @@ Steps are the best way to display a series of actions of events to your users. Y ``` - - -## Steps Props +## Steps properties A list of `Step` components. - The size of the step titles. One of `p`, `h2` and `h3`. + The size of the step titles. One of `p`, `h2`, and `h3`. -## Individual Step Props +## Individual step properties - The content of a step either as plain text, or components. + The content of a step either as plain text or components. - A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}` + A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}`. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` + For Font Awesome icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. @@ -69,5 +65,5 @@ Steps are the best way to display a series of actions of events to your users. Y - The size of the step titles. One of `p`, `h2` and `h3`. + The size of the step titles. One of `p`, `h2`, and `h3`. diff --git a/components/tabs.mdx b/components/tabs.mdx index 42988439c..262291d28 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -1,10 +1,10 @@ --- title: "Tabs" description: "Toggle content using the Tabs component" -icon: 'panel-top' +icon: "panel-top" --- -You can add any number of tabs, and other components inside of tabs. +Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. @@ -26,9 +26,7 @@ You can add any number of tabs, and other components inside of tabs. - - -````mdx Tabs Example +````mdx Tabs example ☝️ Welcome to the content that you can only see inside the first Tab. @@ -49,9 +47,7 @@ You can add any number of tabs, and other components inside of tabs. ```` - - -## Tab Props +## Properties The title of the tab. Short titles are easier to navigate. diff --git a/guides/migration.mdx b/guides/migration.mdx index c72fa6542..98d0b23c8 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -4,7 +4,7 @@ description: "How to migrate documentation from your existing provider" icon: "import" --- -You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. +Use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. We currently support automated migration for: @@ -88,24 +88,26 @@ We currently support automated migration for: -Don't see your docs provider or have a home grown system? We can still help! Please [contact support](/contact-support). +Don't see your documentation provider or have a custom system? We can still help! Please [contact support](/contact-support). ## Commands - `mintlify-scrape section [url]` - Scrapes multiple pages in a site. - `mintlify-scrape page [url]` - Scrapes a single page in a site. -The commands will automatically detect the framework. +The commands automatically detect the framework. ## Installation -First, install the package: +You can install the package globally or for one-time use. + +### Global installation ```bash -npm i @mintlify/scraping +npm install @mintlify/scraping@latest -g ``` -One-time use: +### One-time use @@ -120,26 +122,7 @@ npx @mintlify/scraping@latest page [url] -Global installation: - -```bash -npm install @mintlify/scraping@latest -g -``` - -Global usage: - - - -```bash Section -mintlify-scrape section [url] -``` - - -```bash Page -mintlify-scrape page [url] -``` - - +## OpenAPI migration Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx index 6a98f8a78..c3e13bfbc 100644 --- a/integrations/support/overview.mdx +++ b/integrations/support/overview.mdx @@ -35,9 +35,9 @@ horizontal -## Enabling Support Integrations +## Enabling support integrations -You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `docs.json` file with your respective app ID. +Integrate customer support widgets into your documentation. Add the `integrations` field to your `docs.json` file with your respective app ID. ```json "integrations": { @@ -46,4 +46,4 @@ You can integrate widgets onto your docs for customer support. Add the `integrat } ``` -If you'd like to request a customer support integration, please let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). +Request a new customer support integration in [our Slack community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). diff --git a/quickstart.mdx b/quickstart.mdx index dea8714e5..d6e0b3978 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -6,7 +6,7 @@ icon: "rocket" This quickstart guide shows you how to set up and deploy your documentation site in minutes. -After you complete this guide, you will have a live documentation site ready to customize and expand. +After completing this guide, you will have a live documentation site ready to customize and expand. @@ -14,9 +14,9 @@ After you complete this guide, you will have a live documentation site ready to -## Getting Started +## Getting started -After you complete the onboarding process, your documentation site will automatically deploy to a unique URL with this format: +After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format: ``` https://.mintlify.app @@ -29,18 +29,19 @@ Find your URL on the Overview page of your [dashboard](https://dashboard.mintlif Mintlify Domain -This URL becomes available immediately and updates when you make changes to your documentation. Use this URL for testing and sharing with your team during development. +Your site's URL is available immediately. Use this URL for testing and sharing with your team while you are setting up your docs site. ### Install the GitHub App Mintlify provides a GitHub App that automates deployment when you push changes to your repository. -Install the GitHub App by following the instructions from the onboarding checklist or from your dashboard. +Install the GitHub App by following the instructions from the onboarding checklist or your dashboard. 1. Navigate to **Settings** in your Mintlify dashboard. 2. Select **GitHub App** from the sidebar. 3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page. -4. Select the organization or user account where you want to install the app. Then select the repositories that you want to connect. +4. Select the organization or user account where you want to install the app. +5. Select the repositories that you want to connect. GitHub App Installation @@ -51,7 +52,7 @@ Install the GitHub App by following the instructions from the onboarding checkli Update the GitHub App permissions if you move your documentation to a different repository. -### Authorize your GitHub Account +### Authorize your GitHub account 1. Navigate to **Settings** in your Mintlify dashboard. 2. Select **My Profile** from the sidebar. @@ -61,9 +62,9 @@ Install the GitHub App by following the instructions from the onboarding checkli An admin for your GitHub organization may need to authorize your account depending on your organization settings. -## Editing Workflows +## Editing workflows -Mintlify offers two workflows for creating and maintaining your documentation. +Mintlify offers two workflows for creating and maintaining your documentation: For users who prefer working with existing tools in their local environment. Click to jump to this section. @@ -73,7 +74,7 @@ Mintlify offers two workflows for creating and maintaining your documentation. For users who prefer a visual interface in their web browser. Click to jump to this section. -## Code-Based Workflow +## Code-based workflow The code-based workflow integrates with your existing development environment and Git repositories. This workflow is best for technical teams who want to manage documentation alongside code. @@ -81,33 +82,20 @@ The code-based workflow integrates with your existing development environment an To work locally with your documentation, install the Command Line Interface (CLI), called [mint](https://www.npmjs.com/package/mint), by running this command in your terminal: - - -```bash npm -npm install -g mint -``` - - -```bash yarn -yarn global add mint -``` - - -```bash pnpm -pnpm add -g mint +```bash +npm i -g mint ``` - - You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide. -### Edit the Documentation +### Edit the documentation -After you set up your environment, you can start editing your documentation files. For example, update the title of the introduction page: +After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page: -Open your repository created during onboarding, find the `index.mdx` file, and find the top of the file: +1. Open your repository created during onboarding. +2. Open `index.mdx` and locate the top of the file: ```mdx index.mdx --- @@ -116,7 +104,7 @@ description: "This is the introduction to the documentation" --- ``` -Update the `title` field to `"Hello World"`. +3. Update the `title` field to `"Hello World"`. ```mdx index.mdx {2} --- @@ -125,9 +113,9 @@ description: "This is the introduction to the documentation" --- ``` -### Preview the Changes +### Preview the changes -To preview the changes locally, run this command: +To preview the changes locally, run the following command: ```bash mint dev @@ -140,23 +128,23 @@ Your preview will be available at `localhost:3000`. Mintlify Dev -### Push the Changes +### Push the changes -When you are ready to publish your changes, push the changes to your repository. +When you are ready to publish your changes, push them to your repository. Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com). -After the deployment is complete, your latest update will be available at `.mintlify.app`. +After the deployment completes, your latest update will be available at `.mintlify.app`. Optionally, skip the web editor workflow and jump to adding a custom domain. -## Web Editor Workflow +## Web editor workflow The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. This workflow is best for people who want to work in their web browser without additional local development tools. -### Access the Web Editor +### Access the web editor 1. Log in to your [dashboard](https://dashboard.mintlify.com). 2. Select **Editor** on the left sidebar. @@ -170,7 +158,7 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf The Mintlify web editor in the visual editor mode -### Edit the Documentation +### Edit the documentation In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page: @@ -187,28 +175,28 @@ Then, in the editor, update the title field to "Hello World". The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools. -### Publish Your Changes +### Publish your changes -When you are satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. +When you're satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. Use branches to preview and review changes through pull requests before deploying to your live site. -For more details about using the web editor, including using branches and pull request to collaborate and preview changes, see our [web editor documentation](/editor). +For more details about using the web editor, including using branches and pull requests to collaborate and preview changes, see our [web editor documentation](/editor). -## Adding a Custom Domain +## Adding a custom domain While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation. -To add a custom domain, go to `Settings` > `Custom Domain` from the dashboard. +To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard. Custom Domain Custom Domain -Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS (Domain Name System) settings with your domain provider. +Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider. | Record Type | Name | Value | TTL | @@ -220,7 +208,7 @@ Enter your domain (for example, `docs.yourcompany.com`) and follow the provided DNS changes can take up to 48 hours to propagate, though changes often complete much sooner. -## Next Steps +## Next steps Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation: diff --git a/react-components.mdx b/react-components.mdx index 537ef8eac..336f0c501 100644 --- a/react-components.mdx +++ b/react-components.mdx @@ -9,15 +9,15 @@ import { ColorGenerator } from "/snippets/color-generator.jsx"; [React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation. -You can use React directly in your MDX files without any additional setup. +You can use React components directly in your `MDX` files without any additional setup. -## Using React Components +## Using React components You can build components directly in your MDX files using [React hooks](https://react.dev/reference/react/hooks). -### Basic Example +### Basic example -Here's a basic example of a counter component: +Here is a basic example of a counter component: ```mdx export const Counter = () => { @@ -34,17 +34,17 @@ export const Counter = () => { } ``` -The `Counter` component can then be used in your MDX files like this: +The `Counter` component can be used in your `MDX` files like this: ```mdx ``` -And the component will be rendered as a React component in the MDX file. +The counter renders as an interactive React component. -## Importing Components +## Importing components Just like in regular React, you can import components from other files. @@ -53,10 +53,10 @@ import { ColorGenerator } from "/snippets/color-generator.jsx" ``` - But unlike regular React, you can't import components from every MDX file. Re-usable components can only be referenced from MDX files within the `snippets` folder. + Unlike regular React, you can't import components from every `MDX` file. Reusable components can only be referenced from `MDX` files within the `snippets` folder. -After importing the component, you can use it in your MDX files like this: +After importing the component, use it in your `MDX` files like this: ```mdx @@ -64,9 +64,9 @@ After importing the component, you can use it in your MDX files like this: Learn more about [reusable snippets](/reusable-snippets). -### Complex Example +### Complex example -You can also build much more complex components. Here's an example of a color generator component that uses multiple React hooks: +You can build much more complex components. Here is an example of a color generator component that uses multiple React hooks: ```mdx /snippets/color-generator.jsx [expandable] export const ColorGenerator = () => { @@ -181,30 +181,30 @@ export const ColorGenerator = () => { } ``` -The above component can then be used in your MDX files like this: +The `ColorGenerator` component can be used in your `MDX` files like this: ```mdx ``` -And the component will be rendered as a React component in the MDX file. +The color generator renders as an interactive React component. ## Considerations - + React hook components render on the client-side, which has several implications: - - **SEO**: Search engines might not fully index dynamic content - - **Initial Load**: Visitors may experience a flash of loading content before components render - - **Accessibility**: Ensure dynamic content changes are announced to screen readers + - **SEO**: Search engines might not fully index dynamic content. + - **Initial load**: Visitors may experience a flash of loading content before components render. + - **Accessibility**: Ensure dynamic content changes are announced to screen readers. - - - **Optimize Dependency Arrays**: Include only necessary dependencies in your `useEffect` dependency arrays - - **Memoize Complex Calculations**: Use `useMemo` or `useCallback` for expensive operations - - **Reduce Re-renders**: Break large components into smaller ones to prevent cascading re-renders - - **Lazy Loading**: Consider lazy loading complex components to improve initial page load time + + - **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays. + - **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations. + - **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders. + - **Lazy loading**: Consider lazy loading complex components to improve initial page load time. diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx index 759e040d8..13bda8396 100644 --- a/settings/broken-links.mdx +++ b/settings/broken-links.mdx @@ -1,24 +1,24 @@ --- title: "Redirects and broken links" description: "Tools to help prevent invalid links" -icon: 'link-2' +icon: "link-2" --- -When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title. +When you change the path of a file in your docs folder, it also changes the URL path to that page. This may happen when restructuring your docs or changing the sidebar title. -## Broken Links +## Broken links -Catch broken links with our CLI. Simply [install the CLI](/installation) and run the command: +Catch broken links with our CLI. [Install the CLI](/installation) and run the command: ```bash mint broken-links ``` -The CLI will identify any relative links in your docs that don't exist. +The CLI identifies any relative links in your docs that don't exist. ## Redirects -Set up 301 redirects by adding the `redirects` field into your `docs.json` file. +Set up 301 redirects by adding the `redirects` field to your `docs.json` file. ```json "redirects": [ @@ -29,9 +29,9 @@ Set up 301 redirects by adding the `redirects` field into your `docs.json` file. ] ``` -This will permanently redirect `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. +This permanently redirects `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. -To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`. +To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` matches `/beta/introduction` and redirects it to `/v2/introduction`. ```json "redirects": [ diff --git a/settings/ci.mdx b/settings/ci.mdx index 3d8ced709..d507d2e36 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -5,56 +5,349 @@ icon: "circle-check" --- - CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), an add-on for other plans, and for GitHub. + CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), as an add-on for other plans, and only for GitHub. -Use CI checks to lint your docs for errors, and give you warnings before you deploy. +Use CI checks to lint your docs for errors and provide warnings before you deploy. CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch. ## Installation -To begin, you will need to have followed the steps on the [GitHub](/settings/github) page. +To begin, follow the steps on the [GitHub](/settings/github) page. -For GitHub Apps, you can choose to only give permissions to a single repository. -We highly recommend you do so as we only need access to the repository where -your docs are hosted. +For GitHub Apps, you can choose to give permissions to only a single repository. We highly recommend you do so as we only need access to the repository where your docs are hosted. ## Configuration -You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run. +Configure the CI checks enabled for a deployment by navigating to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard. Enable the checks that you want to run. When enabling checks, you can choose to run them at a `Warning` or `Blocking` level. - +- A `Warning` level check will never provide a failure status, even if there is an error or suggestions. +- A `Blocking` level check will provide a failure status if not passed, or changes are suggested. +## Available CI checks -A `Blocking` level check will provide a failure status if not passed, or changes are suggested.
+### Broken links -A `Warning` level check will never provide a failure status, even if there is an error or suggestions. +Similar to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. - +To see the results of this check, visit GitHub's check results page for a specific commit. -## When Do They Run? +### Vale -CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch. +[Vale](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX. -## Available CI Checks +Mintlify supports automatically running Vale in a CI check and displaying the results as a check status. -### Broken Links +#### Configuration +If you have a `.vale.ini` file in the root content directory for your deployment, we automatically use that configuration file. We also automatically use any configuration files in your specified `stylesPath`. -Similarly to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we will automatically check your docs for broken links. -To see the results of this check, you can visit GitHub's check results page for a specific commit. +If you do not have a Vale config file, the default configuration automatically loads. -### Vale +````mdx Default vale.ini configuration expandable +# Top level styles +StylesPath = /app/styles +MinAlertLevel = suggestion +IgnoredScopes = code, tt, img, url, a +SkippedScopes = script, style, pre, figure, code -[Vale](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX. +# Vocabularies +Vocab = Mintlify -Mintlify supports automatically running Vale in a CI check, and displaying the results as a check status. +# This is required since Vale doesn't officially support MDX +[formats] +mdx = md -#### Configuration -If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file. -We will also automatically use any configuration files in your specified `stylesPath`. +# MDX support +[*.mdx] +BasedOnStyles = Vale +Vale.Terms = NO # Enforces really harsh capitalization rules, keep off -Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that will automatically be used if one is not provided. +# `import ...`, `export ...` +# `` +# `...` +# `{ ... }` +TokenIgnores = (?sm)((?:import|export) .+?$), \ +(?)(?!`), \ +(<[A-Z]\w+>.+?<\/[A-Z]\w+>) + +# Exclude: +# `` +BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ +(?sm)^({.+.*}) + +CommentDelimiters = {/*, */} +```` + +```text Default Vale vocabulary expandable +Mintlify +mintlify +VSCode +openapi +OpenAPI +Github +APIs + +repo +npm +dev + +Lorem +ipsum +impsum +amet + +const +myName +myObject +bearerAuth +favicon +topbar +url +borderRadius +args +modeToggle +ModeToggle +isHidden +autoplay + +_italic_ +Strikethrough +Blockquotes +Blockquote +Singleline +Multiline + +onboarding + +async +await +boolean +enum +func +impl +init +instanceof +typeof +params +stdin +stdout +stderr +stdout +stdin +var +const +let +null +undefined +struct +bool + +cors +csrf +env +xhr +xhr2 +jwt +oauth +websocket +localhost +middleware +runtime +webhook +stdin +stdout + +json +yaml +yml +md +txt +tsx +jsx +css +scss +html +png +jpg +svg + +cdn +cli +css +dom +dto +env +git +gui +http +https +ide +jvm +mvc +orm +rpc +sdk +sql +ssh +ssl +tcp +tls +uri +url +ux +ui + +nodejs +npm +yarn +pnpm +eslint +pytest +golang +rustc +kubectl +mongo +postgres +redis + +JavaScript +TypeScript +Python +Ruby +Rust +Go +Golang +Java +Kotlin +Swift +Node.js +NodeJS +Deno + +React +Vue +Angular +Next.js +Nuxt +Express +Django +Flask +Spring +Laravel +Redux +Vuex +TensorFlow +PostgreSQL +MongoDB +Redis +PNPM + +Docker +Kubernetes +AWS +Azure +GCP +Terraform +Jenkins +CircleCI +GitLab +Heroku + +Git +git +GitHub +GitLab +Bitbucket +VSCode +Visual Studio Code +IntelliJ +WebStorm +ESLint +eslint +Prettier +prettier +Webpack +webpack +Vite +vite +Babel +babel +Jest +jest +Mocha +Cypress +Postman + +HTTP +HTTPS +OAuth +JWT +GraphQL +REST +WebSocket +TCP/IP + +NPM +Yarn +PNPM +Pip +PIP +Cargo +RubyGems + +Swagger +OpenAPI +Markdown +MDX +Storybook +TypeDoc +JSDoc + +MySQL +PostgreSQL +MongoDB +Redis +Elasticsearch +DynamoDB + +Linux +Unix +macOS +iOS + +Firefox +Chromium +WebKit + +config +ctx +desc +dir +elem +err +len +msg +num +obj +prev +proc +ptr +req +res +str +tmp +val +vars + +todo +href +lang +nav +prev +next +toc +``` Please note that for security reasons, we are unable to support any absolute `stylesPath`, or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository. @@ -62,18 +355,18 @@ Please note that for security reasons, we are unable to support any absolute `st #### Packages Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. -Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale configuration. +Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration. -For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they will automatically be downloaded and used in your Vale configuration. +For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they are automatically downloaded and used in your Vale configuration. Please note that for security reasons, we are unable to support automatically downloading packages that are not from the [Vale package registry](https://vale.sh/explorer). -#### Vale with MDX -Vale does not natively support MDX, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. +#### Vale with `MDX` +Vale does not natively support `MDX`, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. -If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: +If you prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: ```ini [formats] mdx = md @@ -89,9 +382,7 @@ BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ (?sm)^({.+.*}) ``` -To use Vale's in-document comments, use MDX-style comments `{/* ... */}`. -If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale will automatically interpret these comments while linting. -This means you can easily use Vale's in-built features, like skipping lines or sections. +To use Vale's in-document comments, use MDX-style comments `{/* ... */}`. If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale automatically interprets these comments while linting. This means you can easily use Vale's built-in features, like skipping lines or sections. ```mdx {/* vale off */} @@ -102,7 +393,7 @@ This text will be ignored by Vale ``` -If you choose not to use `CommentDelimiters`, but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example: +If you choose not to use `CommentDelimiters` but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example: ```mdx {/* */} @@ -111,4 +402,4 @@ This text will be ignored by Vale {/* */} ``` -Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. +These comment tags are not supported within Mintlify components but can be used anywhere at the base level of a document.