diff --git a/content/components/code.mdx b/content/components/code.mdx index d59351bb4..aa4ea3c1c 100644 --- a/content/components/code.mdx +++ b/content/components/code.mdx @@ -4,98 +4,132 @@ description: "Display code with optional syntax highlighting" icon: "code" --- - +Display code snippets with advanced features like syntax highlighting, line highlighting, and custom labels. -````md Code Block Example -```javascript Code Block Example -const hello = "world"; -``` -```` - - +## Basic Usage -## Basic Code Block - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. +Add code by wrapping it in three backticks (```). This is known as a fenced code block. ``` -helloWorld(); +console.log("Hello World"); ``` -````md -``` -helloWorld(); +```md Example +\``` +console.log("Hello World"); +\``` ``` -```` -## Syntax Highlighting +## Adding Language Syntax -Put the name of your programming language after the three backticks to get syntax highlighting. +Make your code blocks prettier by adding syntax highlighting. Just add the language name after the first three backticks. -We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported. - -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} +```javascript +// User data example +const user = { + name: "John", + age: 30, + isAdmin: false +}; ``` -````md -```java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} +```md Example +\```javascript +// User data example +const user = { + name: "John", + age: 30, + isAdmin: false +}; +\``` ``` -```` -## Names + + We support many programming languages including JavaScript, Python, Java, Ruby, and more through [Prism](https://prismjs.com/#supported-languages). Check the full list at [Test Drive Prism](https://prismjs.com/test.html#language=markup). + + +## Adding Labels -You can add more text after the programming language to set the name of your code example. The text can be anything as long as its all in one line. +Add a label to your code block by putting text after the language name. This helps identify what the code example is showing. -```javascript Code Block Example -const hello = "world"; +```python Configuration Example +# Set up database connection +DB_HOST = "localhost" +DB_USER = "admin" +DB_PASS = "secretpassword" ``` -````md Code Block Example -```javascript Code Block Example -const hello = "world"; +```md Example +\```python Configuration Example +# Set up database connection +DB_HOST = "localhost" +DB_USER = "admin" +DB_PASS = "secretpassword" +\``` ``` -```` -## Line Highlighting +## Highlighting Important Lines -You can highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. +Draw attention to specific lines by adding line numbers in curly braces after the label. You can highlight: +- Single lines: `{1}` +- Multiple lines: `{1,3}` +- Line ranges: `{1-3}` -```javascript Line Highlighting Example {1,3-5} -const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); +```javascript Line Highlighting {1,3-4} +const API_KEY = "abc123"; // This line is highlighted +function getData() { + // These lines are highlighted + fetch(`/api/data?key=${API_KEY}`) + .then(response => response.json()); } -sayHello(); ``` -````md -```javascript Line Highlighting Example {1,3-5} -const greeting = "Hello, World!"; -function sayHello() { - console.log(greeting); +```md Example +\```javascript Line Highlighting {1,3-4} +const API_KEY = "abc123"; +function getData() { + // These lines are highlighted + fetch(`/api/data?key=${API_KEY}`) + .then(response => response.json()); } -sayHello(); +\``` ``` -```` -## Code Groups +## Multiple Code Examples -Want to display multiple code examples in one code box? Check out the Code Group docs: +Need to show code in different languages? Use Code Groups to organize multiple examples: - Read the reference for the Code Group component + Learn how to group multiple code examples together + +## Common Use Cases + +Here are some typical ways to use code blocks: + +### API Examples +```javascript +fetch('https://api.example.com/data', { + headers: { + 'Authorization': 'Bearer YOUR_TOKEN' + } +}); +``` + +### Configuration Files +```yaml +version: 1.0 +settings: + theme: dark + notifications: true +``` + +### Command Line Instructions +```bash +npm install mintlify +mintlify dev +``` \ No newline at end of file diff --git a/development.mdx b/development.mdx index 856629aaf..69ecbe23b 100644 --- a/development.mdx +++ b/development.mdx @@ -1,131 +1,126 @@ --- title: 'Local Development' -description: 'Preview changes locally to update your docs' +description: 'Test your documentation changes locally before deploying them' --- - +## Quick Setup -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. +Set up local development in two simple steps to preview your documentation changes. + + **Prerequisite**: Please install [Node.js](https://nodejs.org) version 19 or higher -**Step 1**: Install Mintlify: - - +### Step 1 - Install Mintlify - ```bash npm - npm i -g mintlify - ``` +First, install the Mintlify CLI which lets you preview your docs locally: - ```bash yarn - yarn global add mintlify - ``` + +```bash npm +npm i -g mintlify +``` - ```bash pnpm - pnpm add -g mintlify - ``` +```bash yarn +yarn global add mintlify +``` +```bash pnpm +pnpm add -g mintlify +``` -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: +### Step 2 - Start Development Server + +Go to the docs directory where your `mint.json` is located and run: ```bash mintlify dev ``` -Alternatively, if you do not want to install Mintlify globally you can use a run script available: +The CLI will start a local development server at `http://localhost:3000`. Any changes you make to your documentation will automatically reload in real-time. - - ```bash npm - npx mintlify dev - ``` + + Don't want to install Mintlify globally? You can run it directly using npx: + `npx mintlify dev` + - ```bash yarn - yarn dlx mintlify dev - ``` +## Configuration - ```bash pnpm - pnpm dlx mintlify dev - ``` +### Custom Port - - - - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. - - -A local preview of your documentation will be available at `http://localhost:3000`. - -### Custom Ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +By default, Mintlify runs on port 3000. Use the `--port` flag to use a different port: ```bash mintlify dev --port 3333 ``` -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` +If the specified port is already in use, Mintlify will automatically try the next available port. -## Mintlify Versions +### Versions -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: +Each CLI release is tied to a specific version of Mintlify. If you notice differences between your local preview and the deployed site, you may need to update: +```bash npm +npm i -g mintlify@latest +``` - ```bash npm - npm i -g mintlify@latest - ``` - - ```bash yarn - yarn global upgrade mintlify - ``` - - ```bash pnpm - pnpm up --global mintlify - ``` +```bash yarn +yarn global upgrade mintlify +``` +```bash pnpm +pnpm up --global mintlify +``` -## Validating Links +## Development Tools + +### Link Validation -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +Keep your documentation reliable by checking for broken links. Run this command in your docs directory: ```bash mintlify broken-links ``` -## Deployment +### IDE Setup (Recommended) -If the deployment is successful, you should see the following: +For the best development experience, we recommend: - - - - -## Code Formatting +1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting +2. Install [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for automatic formatting -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting +## Troubleshooting Common Issues - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. + + If you see an error about the "sharp" module on macOS, try these steps: + 1. Remove mintlify: `npm remove -g mintlify` + 2. Update Node.js to v19 or higher 3. Reinstall mintlify: `npm install -g mintlify` - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + If you encounter an unexpected error: + 1. Delete the `~/.mintlify` folder from your home directory + 2. Run `mintlify dev` again + +## Deployment Success + +When your changes are successfully deployed, you'll see a confirmation screen like this: + + + Deployment success screen showing all checks passed + + + + Need help? Join our [Community](https://mintlify.com/community) or contact + [support@mintlify.com](mailto:support@mintlify.com) + \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..ec8c79cba 100644 --- a/mint.json +++ b/mint.json @@ -65,12 +65,17 @@ "icon": "pen-paintbrush", "pages": [ "development", - "web-editor" + "web-editor", + "quickstart" ] }, "settings/global", "settings/navigation", - "migration" + "migration", + "development", + "settings/navigation", + "settings/global", + "snippets/getting-started" ] }, { @@ -257,7 +262,8 @@ "content/components/steps", "content/components/tabs", "content/components/tooltips", - "content/components/update" + "content/components/update", + "content/components/code" ] }, { diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..384bacc51 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,6 +1,6 @@ --- title: "Quickstart" -description: "Start building modern documentation in under five minutes" +description: "Start building your documentation in under five minutes" icon: "rocket" --- @@ -15,172 +15,78 @@ icon: "rocket" /> -## Getting Started +## Getting Started in 3 Steps -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +Get your documentation up and running quickly by following these simple steps: -### Creating the Repository + + + Create your documentation using our [starter template](https://github.com/mintlify/starter). There are two ways to do this: + + 1. **Quick Start**: Use our [dashboard](https://dashboard.mintlify.com) to automatically set everything up + 2. **Manual Setup**: Clone our [starter template](https://github.com/mintlify/starter) repository -Mintlify docs are rendered from MDX files and configurations defined in our -[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate -your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started. + + Installing our GitHub app lets you automatically deploy changes when you push updates. + Find the install link in your [dashboard settings](https://dashboard.mintlify.com/settings). + + - - - - - Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. - - - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - - - - - - If you want your docs to live alongside your code as a monorepo setup, you - can: 1. Move your docs content to your monorepo. 2. Specify the path to your - `mint.json` in the - [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) - - Monorepo setup - Monorepo setup - - - - - -### Updating the Content - -Mintlify enables you to easily customize the style, structure, and content of -your docs. - - - - - 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - 3. Use your favorite IDE to open the repository. - 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. - - Learn more about this in our [local development guide](/development). - - - - - - Learn more about how to use the web editor on our [guide](/web-editor). - - - - - - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: - - ```json - "name": "Your Company" - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg", - "href": "https://yourcompany.com" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#2AB673", - "light": "#55D799", - "dark": "#117866", - }, - ``` - - A full list of supported configurations can be found at [global settings](/settings/global). - - - - - - Add content with simple MDX files. Initiate your pages with this template: - - ```md - --- - title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" - --- - ``` - - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). - - - - - - Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). - - - ![Manual - Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) - - - - - - - You can easily set up your API references using an OpenAPI document. - - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL. - - ```json - "openapi": "link-to-your-openapi-file" - ``` - - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: + + You can edit your documentation in two ways: + 1. **Web Editor (Recommended for beginners)**: Make changes directly in your browser using our [web editor](/web-editor) + 2. **Local Development**: Edit files locally after installing our CLI: ```bash - npx @mintlify/scraping@latest openapi-file + npm i -g mintlify + mintlify dev ``` - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. - - For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). + + Your docs are written in MDX - a powerful combination of Markdown and React components. + Learn more about [writing content](/text) and using our [components](/content/components). + + - + + Once you're ready to publish your changes: - + 1. Commit and push your changes to GitHub + 2. Your docs will automatically update within a few minutes + 3. Need to update manually? Use the [dashboard](https://dashboard.mintlify.com) - Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). - - We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). - - - + + Manual Update + + + + +## Next Steps + +Now that your docs are live, here are some ways to make them even better: + + + + Change colors, add your logo, and configure the navigation to match your brand. + + + Automatically generate API documentation from your OpenAPI/Swagger spec. + + + Track how users interact with your documentation. + + + Host your docs on your own domain (included in free plan). + + - We provide a white-glove migration service as part of our Enterprise plan. - Interested? You can request it by [contacting us](mailto:sales@mintlify.com). + Need help migrating existing docs? We offer white-glove migration services in our Enterprise plan. [Contact us](mailto:sales@mintlify.com) to learn more. -### Publishing - - - -Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan. - -Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain. - -![Custom Domain](/images/custom-domain.png) +## Get Support - +We're here to help you build amazing documentation: -Congrats! You've set up your Mintlify Docs and it's looking amazing! Need -support or want to give some feedback? You can join our -[community](https://mintlify.com/community) or drop us an email at -[support@mintlify.com](mailto:support@mintlify.com). +- Join our [Community](https://mintlify.com/community) +- Email us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file diff --git a/settings/global.mdx b/settings/global.mdx index 350cb3c18..137def5fe 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -1,808 +1,316 @@ --- title: "Global Settings" -description: "Customize your documentation using the mint.json file" +description: "Configure your docs using the mint.json file" icon: "wrench" --- -Every Mintlify site needs a `mint.json` file with the core configuration -settings. Learn more about the [properties](#properties) or from an -[example](#example-mint-json) +## Quick Start -## Properties +Every Mintlify site needs a `mint.json` file in your docs directory. This file controls how your documentation looks and behaves. -### Styling +Here's a basic example to get you started: - - Name of your company or project. Used for the global title. - - - - Path to logo image or object with path to "light" and "dark" mode logo images, - and where the logo links to. SVG format is recommended. It does not pixelate - and the file size is generally smaller. - - - - Path to the logo in light mode. For example: `/path/to/logo.svg` - - - - Path to the logo in dark mode. For example: `/path/to/logo.svg` - - - - Where clicking on the logo links you to - - - - +```json Basic mint.json +{ + "name": "Your Company", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "favicon": "/favicon.png", + "colors": { + "primary": "#0D9373", + "dark": "#0D9373" + }, + "navigation": [ + { + "group": "Getting Started", + "pages": ["introduction", "quickstart"] + } + ] +} +``` - - Path to the favicon image. For example: `/path/to/favicon.svg` - +## Essential Settings - - Hex color codes for your global theme - - - - The primary color. Used most often for highlighted content, section - headers, accents, in light mode - - - - The primary color for dark mode. Used most often for highlighted content, - section headers, accents, in dark mode - - - - The primary color for important buttons - - - - The color of the background in both light and dark mode - - - - The hex color code of the background in light mode - - - - The hex color code of the background in dark mode - - - - - - +These are the core settings you'll want to configure first. - - A preset theme configuration that changes the look and feel of the project. A - theme is a set of default styling configurations. Examples: - [Venus](https://starter-venus.mintlify.app), - [Quill](https://starter-quill.mintlify.app), - [Prism](https://starter-prism.mintlify.app) - +### Branding - - The global layout style of the documentation. + + Your company or project name. Used in the browser title and top navigation. - - Set a decorative background. - - - - The style of the decorative background. - - - + + Your logo. Can be a simple path to an image or an object with different logos for light and dark mode. - - Set a custom background image to be displayed behind every page. - + - - Custom fonts. Apply globally or set different fonts for headings and the body - text. - -Example: +``` -```json -"font": { - "headings": { - "family": "Roboto" - }, - "body": { - "family": "Oswald" +```json Light & Dark Mode +{ + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg", + "href": "https://yoursite.com" } } ``` - - - The font family name. Custom fonts and all [Google - Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans", - "Playfair Display" - - - - The font weight. Precise values such as `560` are also supported for - variable fonts. Check under the Styles section for your Google Font for - the available weights. - - - - The URL to the font file. Can be used to specify a font that is not from - Google Fonts. - - - - The font format. Required if using a custom font source (`url`). - - - - - - - Customize the dark mode toggle. - - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - + - - Customize the styling of components within the sidebar. - - - - The styling of the navigation item. - - - - - - Styling configurations for the topbar. - - - - The styling of the navigation item. - - + + Path to your favicon, shown in browser tabs. SVG or PNG recommended. - - The location options for the search bar. - - - - The location of the search bar. - - - +### Colors - - The style of the rounded edges. - + +Define your brand colors. These are used throughout your docs for consistency. - - The style of the code block. +```json +{ + "colors": { + "primary": "#0D9373", + "light": "#07C983", + "dark": "#0D9373", + "background": { + "light": "#ffffff", + "dark": "#000000" + } + } +} +``` - - - `auto` will automatically switch between light and dark mode based on the - user's system preferences. - - +Use a color contrast checker to ensure your colors are accessible in both light and dark modes. -### Structure +### Navigation - An array of groups with all the pages within that group - - - - The name of the group. - - - - The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array. - - - - The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders. - - - - The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin - + Define the structure of your sidebar. Group pages together and set their order. - - - - - Array of names and urls of links you want to include in the topbar - - - - The name of the button. - - - - The url once you click on the button. Example: `https://mintlify.com/contact` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided - including the number of GitHub stars. - - - - If type is a link: What the button links to. If type is a github: Link to - the repository to load GitHub information from. - - - - Text inside the button. Only required if type is a link. - - - - The style of the button. - - - - Whether to display the arrow - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - -Versions can be leveraged for localization. You can store translated content -under a version, and once you specify the `locale` any fixed text in Mintlify, -such as 'Was this page helpful?', will automatically be translated based on the -locale. We currently support localization in English, Chinese, Spanish, French, -Japanese, and Portuguese. - - - Localization auto-translates the UI and fixed assets in the docs, such as "Was - this page helpful?". You must translate the content of the pages yourself. - - -For more information, please refer to our -[versioning & localization documentation](/settings/versioning). - -Example: - - - ```json Default - "versions": ["v1.0", "v1.1"] - ``` - - ```json Localization - "versions": [ - { - "name": "English", - "locale": "en", - }, +```json +"navigation": [ + { + "group": "Getting Started", + "pages": ["introduction", "quickstart"] + }, + { + "group": "Features", + "pages": [ + "feature-one", { - "name": "Español", - "locale": "es" + "group": "Advanced Features", + "pages": ["advanced/feature-two"] } ] - ``` - - - - - - The version name. - - - - The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`. - - - - Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version. - - - + } +] +``` - - An array of the anchors, includes the icon, color, and url. +## Customization -{" "} +### Themes - - -{" "} - - - - - - The name of the anchor label. - - Example: `Community` - - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - - Used if you want to hide an anchor until the correct docs version is selected. - - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - + + Choose a pre-built theme to quickly style your docs. Examples: + - [Venus](https://starter-venus.mintlify.app) + - [Quill](https://starter-quill.mintlify.app) + - [Prism](https://starter-prism.mintlify.app) - - Override the default configurations for the top-most anchor. Note: if you have - tabs configured, this does not apply. +### Fonts - - - The name of the top-most anchor - + + Customize your typography. Use Google Fonts or your own custom fonts. - - Font Awesome icon. - +```json +{ + "font": { + "headings": { + "family": "Roboto", + "weight": 600 + }, + "body": { + "family": "Open Sans" + } + } +} +``` + - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - +### Layout - + + Set your preferred navigation layout: + - `topnav`: Most common, puts the main nav at the top + - `sidenav`: Puts all navigation in the sidebar + - `solidSidenav`: Like sidenav but with a solid background - - An array of navigational tabs. +## Navigation Elements -Example: +### Top Navigation + + +Add links to the top navigation bar. ```json -"tabs": [ +"topbarLinks": [ { - "name": "Writing Content", - "url": "content" + "name": "Contact Us", + "url": "mailto:support@company.com" }, { - "name": "API References", - "url": "api-playground" + "name": "Help", + "url": "/help" } ] ``` - - - - 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. - - - - Pass `true` if you want to hide the tab until you directly link someone to docs inside it. - - - - - An object to configure the footer with socials and links. - Example: + +Add a call-to-action button to the top navigation. ```json -"footer": { - "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" }, - "links": [ - { - "title": "Column 1", - "links": [ - { "label": "Column 1 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 1 Link 2", "url": "https://mintlify.com" } - ] - }, - { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] - } - ] +"topbarCtaButton": { + "name": "Get Started", + "url": "https://app.company.com", + "type": "link", // or "github" + "style": "pill" // or "roundedRectangle" } ``` - - - - One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter` - - Example: `x` - - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - - Title of the column - - - - The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab. - - - - - Configurations to enable feedback buttons - - - - Enables a rating system for users to indicate whether the page has been helpful - +### Tabs & Anchors - - Enables a button to allow users to suggest edits via pull requests for public repositories. + +Create tab-based navigation at the top of your docs. - - If your docs repo is private, `suggestEdit` will not work. - - - - - Enables a button to allow users to raise an issue about the documentation - - - +```json +"tabs": [ + { + "name": "API Reference", + "url": "api" + }, + { + "name": "Guides", + "url": "guides" + } +] +``` - - Configurations to change the search prompt + +Add anchored sections to your navigation. - - - Set the prompt for the search bar. Default is `Search...` - - +```json +"anchors": [ + { + "name": "Community", + "icon": "comments", + "url": "community", + "color": "#2564eb" + } +] +``` -### API Configurations - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground). - - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground) - - - - By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior. - - Required for select request types, such as file uploads. - - - +## Features - - Configurations for API requests +### Search - - - Configurations for the auto-generated API request examples + +Configure the search functionality. - - - An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java` - - - - - - - - Configurations for the param fields in the API Playground - - - - The default expanded state of expandable options in the API playground. - - `"all"` - every expandable component is expanded - - `"topLevel"` - every top-level expandable component is expanded - - `"topLevelOneOfs"` - every top-level `oneOf` type is expanded - - `"none"` - every expandable component is closed (default behavior) - - - - - +```json +"search": { + "prompt": "Search docs...", + "location": "top" // or "side" +} +``` - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - -Examples: - - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - - ```json Relative - "openapi": "/openapi.json" - ``` +### Feedback - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` + +Add feedback buttons to your pages. - +```json +"feedback": { + "thumbsRating": true, + "suggestEdit": true, + "raiseIssue": true +} +``` ### Integrations - Configurations to add third-party integrations (excluding analytics integrations) - - - - Enables Intercom widget on docs site. The value should be your Intercom App ID. - - - - Enables Frontchat widget on docs site. The value should be your Frontchat App ID. - - - - +Add third-party integrations. - - Configurations to add third-party analytics integrations. See full list of - supported analytics [here](/integrations/analytics/overview). +```json +"integrations": { + "intercom": "your-app-id", + "frontchat": "your-chat-id" +} +``` -### Redirects - - - An array of paths you want to configure to permanently redirect to another path - -Example: +## Advanced Features + ```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" +{ + "api": { + "baseUrl": "https://api.company.com/v1", + "auth": { + "method": "bearer", + "name": "token" + }, + "playground": { + "mode": "show" + } } -] +} ``` + - - - The path that you want to redirect from. - - Example: `/source` - - - - The path that you want to redirect to. - - Example: `/destination` - - - - - -### Search Engine Optimization - - - Settings for Search Engine Optimization. - -Example: - + ```json -"seo": { - "indexHiddenPages": true +{ + "seo": { + "indexHiddenPages": false + }, + "metadata": { + "og:image": "https://company.com/social.jpg" + } } ``` + - - - Enables indexing pages not included in `navigation`. - - - - -## Example `mint.json` - -Click on the following dropdown to view a sample configuration file - - - ```json - { - "name": "Mintlify", - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#16A34A", - "light": "#4ADE80", - "dark": "#166534" - }, - "topbarLinks": [ - { - "name": "Contact Us", - "url": "mailto:support@mintlify.com" - } - ], - "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/start" - }, - "anchors": [ - { - "name": "API Components", - "icon": "rectangle-terminal", - "color": "#f59f0b", - "url": "api-components" - }, - { - "name": "Community", - "icon": "comments", - "color": "#2564eb", - "url": "https://mintlify.com/community" - } - ], - "navigation": [ - { - "group": "Getting Started", - "pages": ["introduction", "quickstart"] - }, - { - "group": "API Components", - "pages": ["api-playground/overview", "api-playground/configuration"] - }, - { - "group": "Settings", - "pages": ["settings/global", "settings/page"] - }, - { - "group": "Analytics", - "pages": ["analytics/posthog"] - } - ], - "footerSocials": { - "github": "https://github.com/mintlify", - "slack": "https://mintlify.com/community", - "x": "https://x.com/mintlify" - }, - "integrations": { - "intercom": "APP_ID", - "frontchat": "CHAT_ID" + +```json +{ + "redirects": [ + { + "source": "/old-page", + "destination": "/new-page" } - } - ``` + ] +} +``` -## More Customization +## Need Help? -Learn more about how to further customize your docs with custom CSS and JS in -[Custom Scripts](https://mintlify.com/docs/advanced/custom/). +Have questions about configuring your docs? Check out our [community](https://mintlify.com/community) or [contact support](mailto:support@mintlify.com). diff --git a/settings/navigation.mdx b/settings/navigation.mdx index ec1ab6e76..8b85672cb 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -1,23 +1,33 @@ --- title: "Navigation" -description: "Organize your docs directory to guide your users to the information they need " +description: "A guide to organizing your documentation structure" icon: "map" --- -## Tabs + + Quick Tip: Every page you add to your docs directory needs to be listed in your `mint.json` navigation to show up in the sidebar. + -Tabs help distinguish between different topics or sections of your -documentation. They show up above the main sidebar. +## Getting Started with Navigation + +Mintlify offers three main ways to organize your documentation: + +1. **Tabs** - For separating major sections (like "API" and "Guides") +2. **Anchors** - For highlighting important sections or external links +3. **Sidebar** - For organizing pages within each section + +Let's look at how to set up each one. + +## 1. Setting Up Tabs + +Tabs appear at the top of your documentation and help separate major sections. - -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of -the tab object should map to a folder of content added to your sidebar, or an -external link. +Add tabs to your `mint.json` like this: ```json "tabs": [ @@ -26,19 +36,19 @@ external link. "url": "api-references" }, { - "name": "Content", - "url": "content" - }, - { - "name": "Blog", - "url": "https://your-website.com/blog" + "name": "Guides", + "url": "guides" } ] ``` -To configure the default `Documentation` primary tab, add the `primaryTab` field -to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. + + The `url` should match the folder name where your content lives. You can also link to external URLs. + + +### Customizing the Main Tab + +Want to rename the default "Documentation" tab? Add this to your `mint.json`: ```json "primaryTab": { @@ -46,193 +56,151 @@ not in a folder reserved by another tab will show up in the primary tab. } ``` -## Anchors +## 2. Adding Anchors -Anchors provide another way to direct users to sections of your documentation, -or link out to external URLs. +Anchors highlight important sections in your docs or link to external resources. - -Configure anchors with the `anchors` field of the `mint.json` file. The `url` -field of the tab object should map an external link, or a folder of content -added to your sidebar. More fields for anchors can be found -[here](/settings/global). +Add anchors to your `mint.json` like this: ```json "anchors": [ { - "name": "API References", + "name": "API Reference", "icon": "code", - "url": "api-references" + "url": "api-reference" }, { - "name": "Content", - "icon": "pencil", - "url": "content" - }, - { - "name": "Contact us", - "icon": "envelope", - "url": "https://mintlify.com/contact-us" + "name": "Community", + "icon": "comments", + "url": "https://mintlify.com/community" } ] ``` -To configure the default `Documentation` top anchor, add the `topAnchor` field -to your `mint.json`. +Each anchor can have: +- A `name` (required) +- An `icon` ([Font Awesome](https://fontawesome.com/icons) icon name) +- A `url` (folder path or external link) -```json -"topAnchor": { - "name": "Home", - "icon": "building" -} -``` +## 3. Organizing the Sidebar -## Sidebar +The sidebar helps users navigate through your documentation pages. -Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) +### Basic Structure - - Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. - +Start with a simple group of pages: -```json Regular Navigation +```json "navigation": [ { "group": "Getting Started", - "pages": ["quickstart"] + "pages": ["quickstart", "installation"] } ] ``` -### Groups +### Creating Nested Groups -Create groups by recursively nesting a group within a group. +Need subgroups? You can nest them like this: -```json Nested Navigation +```json "navigation": [ { "group": "Getting Started", "pages": [ "quickstart", { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] + "group": "Advanced Setup", + "pages": ["configuration", "customization"] } ] } ] ``` -### Folders +### Organizing with Folders -Simply put your MDX files in folders and update the paths in `mint.json`. +You can organize your files into folders for better structure. Here's how it works: -For example, to have a page at `https://yoursite.com/your-folder/your-page` you -would make a folder called `your-folder` containing an MDX file called -`your-page.mdx`. +1. Create a folder (e.g., `guides`) in your docs directory +2. Add your MDX files inside that folder +3. Reference them in your navigation using the folder path - - You cannot use `api` for the name of a folder unless you nest it inside - another folder. Mintlify uses Next.js which reserves the top-level `api` - folder for internal server calls. We recommend using the folder name - `api-reference` instead. - +For example, if you have: +``` +docs/ + └── guides/ + └── basic-setup.mdx +``` - - ```json Navigation With Folder - "navigation": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } - ] - ``` - -```json Nested Navigation +Your navigation would look like: +```json "navigation": [ { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] + "group": "Guides", + "pages": ["guides/basic-setup"] } ] ``` - - -### Hidden Pages - -MDX files not included in `mint.json` will not show up in the sidebar but are -accessible by linking directly to them. - -Hidden pages are not indexed for search within your docs by default. If you -would like to override this behavior, you can set the -[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute -in your `mint.json` to `true`. + + Avoid using `api` as a top-level folder name - it's reserved by Next.js. Use `api-reference` instead. + -## Topbar +## Customizing the Top Bar -### Links +### Adding Links -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. - - - - - -The `topbarLinks` field supports the following fields: `name`, `url`. +Add simple links to the top navigation: ```json - "topbarLinks": [ +"topbarLinks": [ { - "name": "Community", - "url": "https://mintlify.com/community" + "name": "Blog", + "url": "https://mintlify.com/blog" } - ] +] ``` -### CTA Button +### Adding a Call-to-Action Button -Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton` -field. +Make important actions stand out with a CTA button: -The `topbarCtaButton` field supports the following fields: `name`, `url`, `type`, `style`, and `arrow`. For more information on the options for these fields, see the [mint.json schema](/settings/global#structure). - ```json - "topbarCtaButton": { +"topbarCtaButton": { "name": "Get Started", "url": "https://mintlify.com/get-started" - } +} ``` -#### GitHub - -You can also configure the CTA button to link directly to your GitHub -repository. Use the `topbarCtaButton` field with the `type` set to `github`. - - - - +Want to showcase your GitHub repo? Use this instead: ```json - "topbarCtaButton": { +"topbarCtaButton": { "type": "github", "url": "https://github.com/mintlify/docs" - } +} ``` + +## Advanced Features + +### Hidden Pages + +Want pages accessible but not visible in the navigation? +1. Create your MDX file as normal +2. Don't include it in the `navigation` section of `mint.json` + +These pages won't show in the sidebar but are still accessible via direct links. + + + Hidden pages aren't searchable by default. To make them searchable, add `"seo": { "indexHiddenPages": true }` to your `mint.json`. + \ No newline at end of file diff --git a/snippets/getting-started.mdx b/snippets/getting-started.mdx new file mode 100644 index 000000000..0c85759c8 --- /dev/null +++ b/snippets/getting-started.mdx @@ -0,0 +1,124 @@ +# Getting Started with Mintlify + +Welcome! Let's break down the essential concepts and terms you'll need to get started with Mintlify. + +## Key Concepts + + + + Your content lives in MDX files (`.mdx`). These are just like Markdown files but with extra features for interactive components. + + + + Your `mint.json` file controls how your docs look and work. Think of it as your main settings file. + + + + The sidebar and navigation structure of your docs. This helps users find their way around your content. + + + + Pre-built elements like callouts, cards, and code blocks that make your docs more interactive and engaging. + + + +## Quick Setup Steps + + + + Start by creating a new repo for your docs. You can either: + + - Clone our [starter template](https://github.com/mintlify/starter) + - Create a new project in the [Mintlify dashboard](https://dashboard.mintlify.com) + + + + 1. Put your documentation content in `.mdx` files + 2. Organize files into folders for better structure + 3. Update `mint.json` to include your pages in the navigation + + + + ```bash + # Install the Mintlify CLI + npm i -g mintlify + + # Start local preview + mintlify dev + ``` + + Your docs will be available at `http://localhost:3000` + + + +## Basic File Structure + +Here's what a typical Mintlify docs structure looks like: + +```text +your-docs/ +├── mint.json // Main configuration file +├── introduction.mdx // Your home/landing page +├── getting-started/ // A folder for getting started guides +│ ├── quickstart.mdx +│ └── installation.mdx +└── api-reference/ // API documentation (if applicable) + ├── authentication.mdx + └── endpoints.mdx +``` + +## Common MDX Features + +Here are the most frequently used formatting options you'll need: + + + +```mdx Headers +# Main Title +## Section Header +### Subsection +``` + +```mdx Lists +- Bullet point +- Another point + - Nested point + +1. Numbered item +2. Another item +``` + +```mdx Callouts + + Important information goes here + + + + Helpful tips for your users + +``` + + + +## Next Steps + +Once you've got the basics down, you can: + + + + Make your docs interactive with our pre-built components + + + Customize colors, fonts, and layout in mint.json + + + Set up your navigation structure + + + Document your APIs with our interactive playground + + + + + Need help? Join our [Community](https://mintlify.com/community) or check out our [development guide](/development) for detailed instructions. + \ No newline at end of file