diff --git a/content/components/accordion-groups.mdx b/content/components/accordion-groups.mdx new file mode 100644 index 000000000..87fddf9ec --- /dev/null +++ b/content/components/accordion-groups.mdx @@ -0,0 +1,66 @@ +--- +title: "Accordion Groups" +description: "Group multiple accordions into a single display." +icon: "table-rows" +--- + +Simply add `` around your existing `` components. + + + + You can put other components inside Accordions. + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + + + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + + + + +````jsx Accordion Group Example + + + You can put other components inside Accordions. + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + + + Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + +```` + + + +## Props + +`` does not have any props. diff --git a/content/components/accordions.mdx b/content/components/accordions.mdx new file mode 100644 index 000000000..a6254b490 --- /dev/null +++ b/content/components/accordions.mdx @@ -0,0 +1,60 @@ +--- +title: "Accordions" +description: "A dropdown component to toggle content visibility" +icon: "square-caret-down" +--- + + + You can put any content in here, including other components, like code: + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + + +````jsx Accordion Example + + You can put any content in here, including other components, like code: + + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + +```` + + + +## Props + + + Title in the Accordion preview. + + + + Detail below the title in the Accordion preview. + + + + Whether the Accordion is open by default. + + + + A [Font Awesome icon](https://fontawesome.com/icons), [Lucide + icon](https://lucide.dev/icons), or SVG code + + + + One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or + "brands" + + +Use [AccordionGroup](/content/components/accordion-groups) to create a group of Accordions. diff --git a/content/components/callouts.mdx b/content/components/callouts.mdx new file mode 100644 index 000000000..ed7fed70f --- /dev/null +++ b/content/components/callouts.mdx @@ -0,0 +1,47 @@ +--- +title: 'Callout Boxes' +description: 'Use callouts to add eye-catching context to your content' +icon: 'circle-exclamation' +--- + +Callouts can be styled as a Note, Warning, Info, Tip, or Check: + +### Note Callouts + +This adds a note in the content + +```jsx +This adds a note in the content +``` + +### Warning Callouts + +This raises a warning to watch out for + +```jsx +This raises a warning to watch out for +``` + +### Info Callouts + +This draws attention to important information + +```jsx +This draws attention to important information +``` + +### Tip Callouts + +This suggests a helpful tip + +```jsx +This suggests a helpful tip +``` + +### Check Callouts + +This brings us a checked status + +```jsx +This brings us a checked status +``` diff --git a/content/components/card-groups.mdx b/content/components/card-groups.mdx new file mode 100644 index 000000000..e2fbbc6c7 --- /dev/null +++ b/content/components/card-groups.mdx @@ -0,0 +1,49 @@ +--- +title: 'Card Groups' +description: 'Show cards side by side in a grid format' +icon: 'rectangles-mixed' +--- + +The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards in a grid, by specifying the number of grid columns. + + + + Neque porro quisquam est qui dolorem ipsum quia dolor sit amet + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit + + + Ut enim ad minim veniam, quis nostrud exercitation ullamco + + + Excepteur sint occaecat cupidatat non proident + + + + + +```jsx Card Group Example + + + Neque porro quisquam est qui dolorem ipsum quia dolor sit amet + + + Lorem ipsum dolor sit amet, consectetur adipiscing elit + + + Ut enim ad minim veniam, quis nostrud exercitation ullamco + + + Excepteur sint occaecat cupidatat non proident + + +``` + + + +## Props + + + The number of columns per row + diff --git a/content/components/cards.mdx b/content/components/cards.mdx new file mode 100644 index 000000000..b144e164d --- /dev/null +++ b/content/components/cards.mdx @@ -0,0 +1,111 @@ +--- +title: "Cards" +description: "Highlight main points or links with customizable icons" +icon: "rectangle" +--- + + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Card Group page. + + + + ```jsx Card Example + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Card Group page. + + ``` + +```jsx Image Card Example + + Here is an example of a card with an image + +``` + + + +### Horizontal Card + +Add a `horizontal` property to make it horizontally displayed. + + + Here is an example of a horizontal card + + +### Image Card + +Add an `img` property to display an image on the top of the card. + + + Here is an example of a card with an image + + +### Link Card + +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. + + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Card Group page. + + + + ```jsx Card Example + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Card Group page. + + ``` + + +## Props + + + The title of the card + + + + 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` + + + + The color of the icon as a hex code + + + + The url that clicking on the card would navigate the user to + + + + Makes the card more compact and horizontal + + + + The url or local path to an image to display on the top of the card + + + + Label for the action button + + + + Enable or disable the link arrow icon + diff --git a/content/components/icons.mdx b/content/components/icons.mdx new file mode 100644 index 000000000..8936024a6 --- /dev/null +++ b/content/components/icons.mdx @@ -0,0 +1,42 @@ +--- +title: "Icons" +description: "Use [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icons anywhere in the doc" +icon: "icons" +--- + + + + + +```jsx Icon Example + +``` + + +## Inline Icons + +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 + +## Props + + + A [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) icon + + + + One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons). + + + + The color of the icon as a hex code (e.g., `#FF5733`) + + + + The size of the icon in pixels + diff --git a/content/components/responses.mdx b/content/components/responses.mdx new file mode 100644 index 000000000..53e705622 --- /dev/null +++ b/content/components/responses.mdx @@ -0,0 +1,47 @@ +--- +title: 'Response Fields' +description: 'Display API response values' +icon: 'message' +--- + +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. + + + A response field example + + +```jsx + + A response field example + +``` + +## Props + + + The name of the response value. + + + + Expected type of the response value - this can be any arbitrary string. + + + + The default value. + + + + Show "required" beside the field name. + + + + Whether a field is deprecated or not. + + + + Labels that are shown before the name of the field + + + + Labels that are shown after the name of the field + diff --git a/content/components/reusable-components.mdx b/content/components/reusable-components.mdx new file mode 100644 index 000000000..74ab298d0 --- /dev/null +++ b/content/components/reusable-components.mdx @@ -0,0 +1,65 @@ +--- +title: "Reusable Components" +description: "Reusable, custom component snippets" +icon: "recycle" +--- + +Much like custom content [snippets](/reusable-snippets) that can be added in MDX files, you can add reusable components as snippets. + +## Creating a reusable React component + +1. Inside your snippet file, create a component that takes in props by exporting your component in the form of an arrow function. + +```typescript snippets/custom-component.mdx +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 inside of your component. + + +2. Import the snippet into your destination file and pass in the props + +```typescript destination-file.mdx +--- +title: My title +description: My Description +--- + +import { MyComponent } from '/snippets/custom-component.mdx'; + +Lorem ipsum dolor sit amet. + + +``` + + +## Client-Side Content + +By default, Mintlify employs server-side rendering, generating content +at build time. For client-side content loading, ensure to verify the +`document` object's availability before initiating the rendering process. + +```typescript snippets/client-component.mdx +{/* `setTimeout` simulates a React.useEffect, which is called after the component is mounted. */} +export const ClientComponent = () => { + if (typeof document === "undefined") { + return null; + } else { + setTimeout(() => { + const clientComponent = document.getElementById("client-component"); + if (clientComponent) { + clientComponent.innerHTML = "Hello, client-side component!"; + } + }, 1); + + return
+ } +} +``` diff --git a/content/components/tabs.mdx b/content/components/tabs.mdx new file mode 100644 index 000000000..2c0a89736 --- /dev/null +++ b/content/components/tabs.mdx @@ -0,0 +1,58 @@ +--- +title: "Tabs" +description: "Toggle content using the Tabs component" +icon: "window-restore" +--- + +You can add any number of tabs, and other components inside of tabs. + + + + ☝️ Welcome to the content that you can only see inside the first Tab. + You can add any number of components inside of tabs. + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + ✌️ Here's content that's only inside the second Tab. + + + 💪 Here's content that's only inside the third Tab. + + + + + +````jsx Tabs Example + + + ☝️ Welcome to the content that you can only see inside the first Tab. + ```java HelloWorld.java + class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } + } + ``` + + + ✌️ Here's content that's only inside the second Tab. + + + 💪 Here's content that's only inside the third Tab. + + +```` + + + +## Tab Props + + + The title of the tab. Short titles are easier to navigate. + diff --git a/docs.json b/docs.json index 37bf183d7..bde523601 100644 --- a/docs.json +++ b/docs.json @@ -38,7 +38,11 @@ "pages": ["api-reference/introduction"] }, { - "group": "Endpoint Examples", + "group": "Custom Components", + "pages": ["content/components/reusable-components"] + }, + { + "group": "API Components", "pages": [ "api-reference/endpoint/get", "api-reference/endpoint/create", diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx new file mode 100644 index 000000000..c9831cf86 --- /dev/null +++ b/integrations/analytics/overview.mdx @@ -0,0 +1,604 @@ +--- +title: "Analytics Integrations" +description: "Integrate with an analytics platform to track events" +--- + +Automatically send data about your documentation engagement to your third party analytics provider. + +## All Integrations + + + + + +} + /> + + + + + + + } +/> + + + + + + + + + } +/> + + + + + + + + + + + } +/> + + + + + + + + + + + } +/> + + + + + + } +/> + + + + + + } +/> + + + + + + + } +/> + + + + + + + + + + + + + + + + + + + + + + + + + + + + } +/> + + + + + + + + + + + + + + + + + + + + + + + + + + + } +/> + + + + + + + +} +/> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + } +/> + + + + + + } +/> + + + + + + + + +} + /> + + +## Enabling Analytics + +Set your analytics keys in `docs.json`. You can add an unlimited number of analytics integrations for free. + +The syntax for `docs.json` is below. You only need to include entries for the platforms you want to connect. + +```json Analytics options in docs.json +"integrations": { + "amplitude": { + "apiKey": "required" + }, + "clearbit": { + "publicApiKey": "required" + }, + "cookies": { + "key": "required", + "value": "required" + }, + "fathom": { + "siteId": "required" + }, + "ga4": { + "measurementId": "required" + }, + "gtm": { + "tagId": "required" + }, + "hotjar": { + "hjid": "required", + "hjsv": "required" + }, + "koala": { + "publicApiKey": "required" + }, + "logrocket": { + "appId": "required" + }, + "mixpanel": { + "projectToken": "required" + }, + "pirsch": { + "id": "required" + }, + "plausible": { + "domain": "required" + }, + "posthog": { + "apiKey": "required", + "apiHost": "optional" + }, + "segment": { + "key": "required" + }, + "telemetry": { + "enabled": "boolean" + } +} +``` + +## FAQ + + + +- `expandable_open` +- `expandable_close` +- `accordion_open` +- `accordion_close` +- `header_nav_item_click` +- `cta_click` +- `scroll_to_bottom` +- `search_close` +- `api_playground_call` +- `search_result_click` +- `chat_enter` +- `chat_followup` +- `chat_completed` +- `code_block_copy` +- `chat_shared` +- `thumb_vote` +- `powered_by_mintlify_click` +- `ai_chat_citation_click` +- `ai_chat_feedback_positive_click` +- `ai_chat_feedback_negative_click` +- `pageview` + + diff --git a/list-table.mdx b/list-table.mdx new file mode 100644 index 000000000..51ab4957f --- /dev/null +++ b/list-table.mdx @@ -0,0 +1,86 @@ +--- +title: "Lists and Tables" +description: "Display information in lists and tables" +icon: "list" +--- + + +## Lists + +### Ordered List + +To create an ordered list, add line items with numbers followed by periods + +1. First item +2. Second item +3. Third item +4. Fourth item + +```md +1. First item +2. Second item +3. Third item +4. Fourth item +``` + +### Unordered List + +To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items. + +- First item +- Second item +- Third item +- Fourth item + +```md +- First item +- Second item +- Third item +- Fourth item +``` + +### Nested List + +Add indents on list items to nest them + +- First item +- Second item + - Additional item + - Additional item +- Third item + +```md +- First item +- Second item + - Additional item + - Additional item +- Third item +``` + + + Lists follow the official [markdown syntax](https://www.markdownguide.org/basic-syntax/#lists-1). + + +## Tables + +| Property | Description | +| -------- | ------------------------------------- | +| Name | Full name of user | +| Age | Reported age | +| Joined | Whether the user joined the community | + +### Creating a table + + + The Table component follows the official [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables). + + +To add a table, use three or more hyphens (`---`) to create each column's header, and use pipes (`|`) to separate each column. For compatibility, you should also add a pipe on either end of the row. + +```md +| Property | Description | +| -------- | ------------------------------------- | +| Name | Full name of user | +| Age | Reported age | +| Joined | Whether the user joined the community | +``` \ No newline at end of file diff --git a/migration.mdx b/migration.mdx new file mode 100644 index 000000000..3b25abaa9 --- /dev/null +++ b/migration.mdx @@ -0,0 +1,151 @@ +--- +title: "Migration" +description: "How to migrate documentation from your existing provider" +icon: "arrow-up-from-bracket" +--- + +You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. + +We currently support migration for: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +} horizontal> + + + + +} horizontal> + + + + +Don't see your docs provider or have a home grown system? We can still help\! Please get in touch at [support@mintlify.com](mailto:sales@mintlify.com). + +## 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. + +## Installation + +First, install the package: + +``` +npm i @mintlify/scraping +``` + +One-time use: + + + +```bash Section +npx @mintlify/scraping@latest section [url] +``` + + +```bash Page +npx @mintlify/scraping@latest page [url] +``` + + + +Global installation: + +``` +npm install @mintlify/scraping@latest -g +``` + +Global usage: + + + +```bash Section +mintlify-scrape section [url] +``` + + +```bash Page +mintlify-scrape page [url] +``` + + + +Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. + +``` +mintlify-scrape openapi-file [openApiFilename] + +-w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true] +-o, --outDir The folder in which to write any created frontmatter files [string] +``` \ No newline at end of file diff --git a/reusable-snippets.mdx b/reusable-snippets.mdx new file mode 100644 index 000000000..43d5bfc7a --- /dev/null +++ b/reusable-snippets.mdx @@ -0,0 +1,97 @@ +--- +title: 'Reusable Snippets' +description: 'Reusable, custom snippets to keep content in sync' +icon: 'recycle' +--- + +One of the core principles of software development is DRY (Don't Repeat +Yourself), which applies to documentation as +well. If you find yourself repeating the same content in multiple places, you +should create a custom snippet to keep your content in sync. + +## Creating a custom snippet + +**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work. + + 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. + + +### Default export + +1. Add content to your snippet file that you want to re-use. Optionally, you can add variables that can be filled in via props + when you import the snippet. In this example, our variable is word. + +```typescript snippets/my-snippet.mdx +Hello world! This is my content I want to reuse across pages. +``` + +2. Import the snippet into your destination file. + +```typescript destination-file.mdx +--- +title: My title +description: My Description +--- + +import MySnippet from '/snippets/path/to/my-snippet.mdx'; + +## Header + +Lorem impsum dolor sit amet. + + + +``` + +### Exporting with variables + +1. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word. + +```typescript snippets/my-snippet.mdx +My keyword of the day is {word}. +``` + + +2. Import the snippet into your destination file with the variable. The property will fill in based on your specification. + +```typescript destination-file.mdx +--- +title: My title +description: My Description +--- + +import MySnippet from '/snippets/path/to/my-snippet.mdx'; + +## Header + +Lorem impsum dolor sit amet. + + + +``` + +### Reusable variables + +1. Export a variable from your snippet file: + +```typescript snippets/path/to/custom-variables.mdx +export const myName = 'my name'; + +export const myObject = { fruit: 'strawberries' }; +``` + +2. Import the snippet from your destination file and use the variable: + +```typescript destination-file.mdx +--- +title: My title +description: My Description +--- + +import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; + +Hello, my name is {myName} and I like {myObject.fruit}. +``` diff --git a/search.mdx b/search.mdx new file mode 100644 index 000000000..defc24089 --- /dev/null +++ b/search.mdx @@ -0,0 +1,44 @@ +--- +title: "Search" +description: "Learn how our search ranks results and discover tips for structuring your content to improve its discoverability" +icon: "file-magnifying-glass" +--- + +## Search Result Ranking + +Our search functionality combines two main techniques to deliver relevant results: + +1. **Prefix Matching:** If your search query exactly matches the beginning of a word in the content (like searching for "insta" matching "install"), those results are given the highest priority. +2. **Full-Text Search:** For broader matches, our search scans your entire content to find results based on the words present in the content. + +### Boosting Relevance + +To ensure the most important content surfaces first, we apply boosts: + +* **Page Titles:** Titles receive the most significant boost as they usually represent the main topic of a page. +* **Sub-headings:** Headings within a page are also boosted, but to a lesser extent, to highlight key sections. + +### Content Chunking + +To provide more granular and relevant results, search operates on content "chunks." Content is broken down as follows: + +* **Page-level:** The title and description of each page form a primary chunk. +* **Section-level:** Each heading and the content immediately following it create additional, more specific chunks. This helps users find the most relevant section within a page. + + Content appearing before the first heading on a page, or on pages without any headings, is associated with the main page-level chunk for search purposes. + +## Version and Language Filtering + +Search results are automatically filtered based on the version and language you have selected for browsing the documentation. +Results will also include content not specific to any version that matches the query. + +## Optimizing Content for Search + +Here are some recommendations for structuring your content to work well with our search features: + +* **Use Clear and Descriptive Titles:** Ensure titles accurately reflect the page's main topic and include terms users are likely to search for. +* **Structure with Headings:** Utilize headings to break down content logically and create effective searchable chunks. Clear headings make content easier to understand. +* **Include Relevant Keywords:** Incorporate the words and phrases your audience is likely to use naturally within your sentences. +* **Keep Sections Focused:** Ensure the text under each heading directly relates to that topic to improve the accuracy of search results pointing to specific sections. +* **Write Concise Descriptions:** Craft clear page descriptions that summarize the content and include primary keywords. + diff --git a/table.mdx b/table.mdx new file mode 100644 index 000000000..c18543dbe --- /dev/null +++ b/table.mdx @@ -0,0 +1,26 @@ +--- +title: "Tables" +description: "Display an arrangement of data in rows and columns" +--- + +| Property | Description | +| -------- | ------------------------------------- | +| Name | Full name of user | +| Age | Reported age | +| Joined | Whether the user joined the community | + +### Creating a table + + + The Table component follows the official [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables). + + +To add a new table, use three or more hyphens (`---`) to create each column's header, and use pipes (`|`) to separate each column. For compatibility, you should also add a pipe on either end of the row. + +```md +| Property | Description | +| -------- | ------------------------------------- | +| Name | Full name of user | +| Age | Reported age | +| Joined | Whether the user joined the community | +``` \ No newline at end of file