diff --git a/development.mdx b/development.mdx index 856629aaf..9bcdaf433 100644 --- a/development.mdx +++ b/development.mdx @@ -1,18 +1,28 @@ --- -title: 'Local Development' -description: 'Preview changes locally to update your docs' +title: "Local Development" +description: "Preview changes locally to update your docs" --- - +/ + + + +--- +title: "Local Development" +description: "Preview changes locally to update your docs" +--- -**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. +| test | table | +| ---- | ----- | +| | | + + **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. **Step 1**: Install Mintlify: - ```bash npm npm i -g mintlify ``` @@ -24,7 +34,6 @@ description: 'Preview changes locally to update your docs' ```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: @@ -47,7 +56,6 @@ Alternatively, if you do not want to install Mintlify globally you can use a run ```bash pnpm pnpm dlx mintlify dev ``` - @@ -75,7 +83,6 @@ Port 3000 is already in use. Trying 3001 instead. 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: - ```bash npm npm i -g mintlify@latest ``` @@ -87,7 +94,6 @@ Please note that each CLI release is associated with a specific version of Mintl ```bash pnpm pnpm up --global mintlify ``` - ## Validating Links @@ -103,10 +109,7 @@ mintlify broken-links If the deployment is successful, you should see the following: - + ## Code Formatting @@ -116,16 +119,17 @@ We suggest using extensions on your IDE to recognize and format MDX. If you're a ## Troubleshooting - - + 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` - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. - + \ No newline at end of file diff --git a/migration.mdx b/migration.mdx index 491e89454..a289b6aa9 100644 --- a/migration.mdx +++ b/migration.mdx @@ -4,95 +4,110 @@ 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 scrape documentation frameworks to Mintlify. +You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to scrape documentation frameworks to Mintlify. We currently support migration for: + - - - + + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - -} /> - + +} + /> + + -} /> - - -} /> +} + /> + + + +} + /> -Don't see your docs provider or have a home grown system? We can still help! Please get in touch at sales@mintlify.com. +Don't see your docs provider or have a home grown system? We can still help! Please get in touch at [sales@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. +* `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. @@ -105,14 +120,15 @@ npm i @mintlify/scraping ``` One-time use: + -```bash Section -npx @mintlify/scraping@latest section [url] -``` + ```bash Section + npx @mintlify/scraping@latest section [url] + ``` -```bash Page -npx @mintlify/scraping@latest page [url] -``` + ```bash Page + npx @mintlify/scraping@latest page [url] + ``` Global installation: @@ -124,18 +140,17 @@ npm install @mintlify/scraping@latest -g Global usage: -```bash Section -mintlify-scrape section [url] -``` + ```bash Section + mintlify-scrape section [url] + ``` -```bash Page -mintlify-scrape page [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] diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..5e3212931 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -5,58 +5,57 @@ icon: "rocket" --- - - + + + ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify. + +start + + + Callout Content + -### Creating the Repository + + + + Callout Content + + example + + +## 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. +your docs with your code, and make source control effortless. + + If you've created a docs repo in our onboarding, this step is complete. You can find your docs repository on your Mintlify [dashboard](https://dashboard.mintlify.com). + + To create your docs repo without logging into GitHub, follow these instructions: + + 1. Clone our [starter template](https://github.com/mintlify/starter) into a new public repo. You can make the repo private later. - - - 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. + 2. [Get in touch](mailto:support@mintlify.com) with our team to deploy your repo. - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) + ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.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 - - + + The next step is to install our GitHub app. This ensures 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) + + ### Updating the Content @@ -66,24 +65,22 @@ 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 @@ -102,11 +99,9 @@ your docs. ``` 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 @@ -118,22 +113,17 @@ your docs. ``` 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) - - + + ![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. @@ -151,15 +141,12 @@ your docs. 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). - - 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). - @@ -171,16 +158,16 @@ your docs. ### Publishing + Integrate your docs into your website by hosting them on a custom domain. This is included even in the free plan. -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) + 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). +[support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file