diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index c222ffedf..64ad5431e 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -6,10 +6,57 @@ hideApiMarker: true icon: 'play' --- -The API playground is an interactive environment to make requests and preview an API endpoint. +## What is the API Playground? + +The API playground is an interactive environment that lets users test your API endpoints directly from your documentation. Think of it as a built-in API testing tool where users can: + +- Make real API requests +- See exactly how the API behaves +- Test different parameters and inputs +- View formatted responses + + + Example of the API Playground interface + + +## Key Benefits + + + + Users can learn your API hands-on instead of just reading about it + + + Test endpoints instantly without setting up a separate API client + + + See actual API responses with your real data + + + Understand how errors work by triggering them safely + + + +## Getting Started + +The easiest way to add API playground to your docs is by using OpenAPI (formerly known as Swagger). When you use OpenAPI: + +1. The playground is automatically generated for each endpoint +2. All parameters and response formats are pre-configured +3. Authentication is handled automatically - Autogenerating API pages with OpenAPI will automatically generate API - playground. Read more about using OpenAPI with Mintlify - [here](/api-playground/openapi). + Want to add API playground using OpenAPI? Check out our [OpenAPI setup guide](/api-playground/openapi) for step-by-step instructions. + +Don't have an OpenAPI specification? No problem! You can also set up the playground manually for each endpoint. We'll walk you through that in our [manual configuration guide](/api-playground/mdx). + +## Example + +Here's an example of what an API playground looks like when set up. Try making a request below: + + +This is a live API playground example. Feel free to: +- Change the parameters +- Click "Send API Request" +- See the actual response + \ No newline at end of file diff --git a/development.mdx b/development.mdx index a36c3c707..7b78c7f44 100644 --- a/development.mdx +++ b/development.mdx @@ -1,78 +1,93 @@ --- title: 'Local Development' -description: 'Preview changes locally to update your docs' +description: 'Set up and preview your documentation locally' --- -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - +## Before You Start +**Prerequisites**: +- Install Node.js version 19 or higher ([download here](https://nodejs.org/en)) +- Basic familiarity with command line/terminal -**Step 1**: Install Mintlify: - - +## Installation and Setup - ```bash npm - npm i -g mintlify - ``` + + + Choose any of the following package managers to install Mintlify globally on your machine: - ```bash yarn - yarn global add mintlify - ``` + - ```bash pnpm - pnpm add -g mintlify - ``` + ```bash npm + npm i -g mintlify + ``` - + ```bash yarn + yarn global add mintlify + ``` -**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command: + ```bash pnpm + pnpm add -g mintlify + ``` -```bash -mintlify dev -``` + + -Alternatively, if you do not want to install Mintlify globally you can use a run script available: + + Navigate to your docs folder (where `docs.json` is located) and run: - - ```bash npm - npx mintlify dev - ``` + ```bash + mintlify dev + ``` - ```bash yarn - yarn dlx mintlify dev - ``` + The preview will be available at `http://localhost:3000`. - ```bash pnpm - pnpm dlx mintlify dev - ``` + + Don't want to install Mintlify globally? You can run it directly: + + ```bash npm + npx mintlify dev + ``` - + ```bash yarn + yarn dlx mintlify dev # Requires yarn >2 + ``` - - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. - + ```bash pnpm + pnpm dlx mintlify dev + ``` + + + + -A local preview of your documentation will be available at `http://localhost:3000`. +## Common Configuration Options -### Custom Ports +### Change Preview Port -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. You can use a different port by adding the `--port` flag: ```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 +If the specified port is in use, Mintlify will automatically try the next available port: +```bash Port 3000 is already in use. Trying 3001 instead. ``` -## Mintlify Versions +### Check for Broken Links + +Keep your documentation reliable by checking for broken links: + +```bash +mintlify broken-links +``` + +## Updating Mintlify -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 corresponds to a specific version of Mintlify. To ensure you have the latest features and fixes, update regularly: @@ -90,42 +105,57 @@ Please note that each CLI release is associated with a specific version of Mintl -## Validating Links +## Editor Setup -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +For the best development experience, we recommend: -```bash -mintlify broken-links -``` - -## Deployment - -If the deployment is successful, you should see the following: - - - - - -## Code Formatting +1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting +2. Install [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code 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 Guide - + + If you see `Error: Could not load the "sharp" module using the darwin-arm64 runtime`, follow these steps: + + 1. Remove current Mintlify installation: + ```bash + npm remove -g mintlify + ``` + + 2. Upgrade Node.js to v19 or higher + 3. Reinstall Mintlify: + ```bash + npm install -g mintlify + ``` + - 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. - 3. Reinstall mintlify: `npm install -g mintlify` + + If you encounter unexpected errors: + 1. Delete the Mintlify cache folder: + ```bash + rm -rf ~/.mintlify + ``` + + 2. Restart the development server: + ```bash + mintlify dev + ``` - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + + When your deployment succeeds, you should see green checkmarks in your deployment status: + + + Successful deployment checks + + + + Need more 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/quickstart.mdx b/quickstart.mdx deleted file mode 100644 index 76ec6868b..000000000 --- a/quickstart.mdx +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: "Quickstart" -description: "Start building modern documentation in under five minutes" -icon: "rocket" ---- - - - - - - -## Getting Started - -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. - -### Creating the 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. - - - - - - 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 - `docs.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 `docs.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 `docs.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: - - ```bash - npx @mintlify/scraping@latest openapi-file - ``` - - 3. Finally, include the generated endpoint MDX files to your `docs.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). - - - - - - 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). - - - - - - 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). - - -### 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) - - - -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). diff --git a/settings/global.mdx b/settings/global.mdx index 0473031ba..818b94fc4 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -10,7 +10,7 @@ Every documentation site requires a `docs.json` file that contains the core conf -## Properties +Every Mintlify site needs a `mint.json` file to configure your documentation. This file controls site-wide settings like: ### Customization @@ -1188,22 +1188,17 @@ Example: "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" } - ] + "group": "Getting Started", + "pages": ["introduction", "quickstart"] }, { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] + "group": "Guides", + "pages": ["guides/installation", "guides/configuration"] } ] } ``` + @@ -1457,9 +1452,9 @@ Example: -## Example `mint.json` + -Click on the following dropdown to view a sample configuration file +## Advanced Features ```json diff --git a/snippets/getting-started.mdx b/snippets/getting-started.mdx new file mode 100644 index 000000000..a72b39bf9 --- /dev/null +++ b/snippets/getting-started.mdx @@ -0,0 +1,113 @@ +## What is Mintlify? + +Mintlify helps you create beautiful documentation that your users will love. Think of it like building a website, but specifically designed for documentation with pre-built components and features that developers need. + +## Common Use Cases + + + + Document your API endpoints with interactive examples and code snippets + + + Create user guides and tutorials for your product features + + + Build a central hub for all your technical documentation + + + Maintain private documentation for your team + + + +## Quick Setup Guide + + + + Start by creating a new repository using our [starter template](https://github.com/mintlify/starter). This gives you a pre-configured setup with example pages. + + ```bash + git clone https://github.com/mintlify/starter.git my-docs + ``` + + + + Replace the content in the starter template with your own documentation: + + 1. Update `mint.json` with your site name and navigation + 2. Replace the MDX files in the starter with your own content + 3. Add your logo and favicon to the `/public` folder + + + Keep the example pages around until you're comfortable with how everything works. They're great reference material! + + + + + Install our CLI to preview your docs as you work: + + ```bash + npm i -g mintlify + mintlify dev + ``` + + Your docs will be available at `http://localhost:3000` + + + + Once you're ready, push your changes to GitHub and connect your repository in our [dashboard](https://dashboard.mintlify.com). We'll automatically build and deploy your docs. + + + +## Frequently Asked Questions + + + + No! While being familiar with Markdown is helpful, you don't need any coding experience. Our visual editor lets you make changes without touching any code. + + + + Yes! You can use any domain you own. We provide instructions for setting up custom domains in our [domains guide](/settings/custom-domain). + + + + Start with broad categories and break them down into smaller topics. Use our [navigation guide](/settings/navigation) to structure your docs in a way that makes sense for your users. + + + + Documentation sites are optimized for: + - Search and navigation + - Code examples and API references + - Version control and collaboration + - Technical content organization + + + +## Need Help? + + + + Get help from other developers and share your questions + + + Reach out to our team directly if you need assistance + + + +## Next Steps + +Once you've got the basics down, explore these features: + + + + Create interactive API documentation + + + Match your brand's look and feel + + + Use our pre-built MDX components + + + Track how users interact with your docs + + \ No newline at end of file