Skip to content

Improve Documentation Readability and Onboarding Experience #470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
+619 −1,104
Closed

Improve Documentation Readability and Onboarding Experience #470

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 65 additions & 56 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
---
title: 'Local Development'
description: 'Preview changes locally to update your docs'
description: 'Set up your docs locally to preview changes before updating your site'
---

<Info>
**Before you start**: Make sure you have Node.js version 19 or higher installed. You can download it from the [Node.js website](https://nodejs.org).
</Info>

**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
## Setting Up Local Development

</Info>
Get your documentation running locally in three simple steps:

**Step 1**: Install Mintlify:
### Step 1: Install the Mintlify CLI

<CodeGroup>
The Mintlify CLI (Command Line Interface) helps you run and test your documentation locally. Install it using one of these commands:

<CodeGroup>
```bash npm
npm i -g mintlify
```
Expand All @@ -24,58 +27,65 @@ description: 'Preview changes locally to update your docs'
```bash pnpm
pnpm add -g mintlify
```

</CodeGroup>

**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:

```bash
mintlify dev
```

Alternatively, if you do not want to install Mintlify globally you can use a run script available:
Don't want to install globally? You can run it directly:

<CodeGroup>
```bash npm
npx mintlify dev
```

```bash yarn
yarn dlx mintlify dev
yarn dlx mintlify dev # Requires yarn >2
```

```bash pnpm
pnpm dlx mintlify dev
```

</CodeGroup>

<Warning>
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
</Warning>
### Step 2: Go to Your Docs Folder

Navigate to the folder containing your docs (where your `mint.json` file is located).

### Step 3: Start the Development Server

Run this command to start your local docs:

```bash
mintlify dev
```

A local preview of your documentation will be available at `http://localhost:3000`.
Once started, you can view your documentation at `http://localhost:3000`. The preview updates automatically when you save changes to your files.

### Custom Ports
## Common Tasks

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:
### Using a Different Port

By default, Mintlify runs on port 3000. To use a different port, add 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:
If the port you specify is already in use, Mintlify will automatically try the next available port.

### Checking for Broken Links

```md
Port 3000 is already in use. Trying 3001 instead.
Keep your documentation reliable by checking for broken links:

```bash
mintlify broken-links
```

## Mintlify Versions
This command scans your docs and reports any broken internal links.

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:
### Updating Mintlify

<CodeGroup>
If your local preview looks different from your deployed site, you might need to update Mintlify. Use one of these commands:

<CodeGroup>
```bash npm
npm i -g mintlify@latest
```
Expand All @@ -87,45 +97,44 @@ Please note that each CLI release is associated with a specific version of Mintl
```bash pnpm
pnpm up --global mintlify
```

</CodeGroup>

## Validating Links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
## Editor Setup

```bash
mintlify broken-links
```
To make editing documentation easier, we recommend installing:

## Deployment

If the deployment is successful, you should see the following:

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
/>
</Frame>

## 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.
1. [MDX VS Code Extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) - Adds syntax highlighting for MDX files
2. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Helps format your code consistently

## Troubleshooting

<AccordionGroup>
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
Here are solutions to common issues you might encounter:

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.
<AccordionGroup>
<Accordion title="Package 'sharp' Not Loading">
If you see an error about the "sharp" module not loading for darwin-arm64, follow these steps:
1. Remove mintlify: `npm remove -g mintlify`
2. Update Node.js to version 19 or higher
3. Reinstall mintlify: `npm install -g mintlify`
</Accordion>

<Accordion title="Issue: Encountering an unknown error">

Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
<Accordion title="Unknown Errors">
If you encounter any unexpected errors:
1. Go to your root directory
2. Delete the hidden ~/.mintlify folder
3. Run `mintlify dev` again
</Accordion>

<Accordion title="Changes Not Showing Up">
If your changes aren't appearing in the preview:
1. Check that you're in the correct directory (where mint.json is located)
2. Make sure you've saved your files
3. Try refreshing your browser
4. Restart the development server
</Accordion>
</AccordionGroup>

<Note>
Need more help? Join our [community](https://mintlify.com/community) or contact
[[email protected]](mailto:[email protected])
</Note>
3 changes: 2 additions & 1 deletion mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@
},
"settings/global",
"settings/navigation",
"migration"
"migration",
"snippets/developer-guide"
]
},
{
Expand Down
Loading
Loading