Skip to content

Improve quickstart page according to style guide #749

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve quickstart page according to style guide #749

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e07bf7
Documentation edits made through Mintlify web editor
mintlify[bot] May 28, 2025
0da80e9
Documentation edits made through Mintlify web editor
mintlify[bot] May 28, 2025
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
124 changes: 65 additions & 59 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
icon: "rocket"
---

This quickstart guide will walk you through the process of setting up and deploying your documentation site in just a few minutes.

By the end of this guide, you'll have a live documentation site that's ready to customize and expand.

<Info>
Expand All @@ -16,54 +14,55 @@

## Getting Started

Once you've completed the onboarding process, your documentation site will be automatically deployed to a unique URL with the following format.
Once you've completed the onboarding process, your documentation site will be automatically deployed to a unique URL with the following format:

```
https://<your-project-name>.mintlify.app
```

You can find your URL from the Overview page of the dashboard.

<Frame>
<img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify Domain" className="block dark:hidden" />
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify Domain" className="hidden dark:block" />
<Frame caption="Your unique documentation URL appears in the dashboard overview">
<img src="/images/quickstart/mintlify-domain-light.png" alt="Dashboard overview showing the unique documentation URL with project name" className="block dark:hidden" />
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Dashboard overview showing the unique documentation URL with project name in dark mode" className="hidden dark:block" />
</Frame>

This URL is instantly available and will update whenever you make changes to your documentation. It's perfect for testing and sharing with your team during development.
This URL is instantly available and updates whenever you make changes to your documentation. It's perfect for testing and sharing with your team during development.

### Install the GitHub App

Mintlify provides a GitHub App that automates the deployment process when you push changes to your repository.
The GitHub App automates the deployment process when you push changes to your repository.

You can install the GitHub App by following the instructions from the onboarding checklist or from your dashboard.
You can install the GitHub App by following the instructions from the onboarding checklist or from your dashboard:

1. Navigate to **Settings** in your Mintlify dashboard.
2. Select **GitHub App** from the sidebar.
3. Select **Install GitHub App**. This will open a new tab to the GitHub App installation page.
4. Select the organization or user account where you want to install the app. Then select the repositories that you want to connect.
1. Navigate to **Settings** in your dashboard
2. Select **GitHub App** from the sidebar
3. Select **Install GitHub App** (this opens a new tab to the GitHub App installation page)
4. Select the organization or user account where you want to install the app
5. Select the repositories you want to connect

<Frame>
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App Installation" className="block dark:hidden" />
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App Installation" className="hidden dark:block" />
<Frame caption="Installing the GitHub App connects your repository for automatic deployments">
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub App installation page showing organization and repository selection options" className="block dark:hidden" />
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub App installation page showing organization and repository selection options in dark mode" className="hidden dark:block" />
</Frame>

<Info>
Remember to update the GitHub App permissions if you move the documentation to a different repository.
</Info>

### Authorize your GitHub Account
### Authorize Your GitHub Account

1. Navigate to **Settings** in your Mintlify dashboard.
2. Select **My Profile** from the sidebar.
3. Select **Authorize GitHub account**. This will open a new tab to the GitHub authorization page.
1. Navigate to **Settings** in your dashboard
2. Select **My Profile** from the sidebar
3. Select **Authorize GitHub account** (this opens a new tab to the GitHub authorization page)

<Info>
You may need an admin for your GitHub organization to authorize your account depending on your organization's settings.
</Info>

## Editing Workflows

Mintlify offers two different workflows for creating and maintaining your documentation.
Choose between two workflows for creating and maintaining your documentation:

<Card title="Code-based workflow" icon="terminal" horizontal href="#code-based-workflow">
For developers who prefer working with their existing tools. Click to jump to section.
Expand All @@ -87,12 +86,10 @@
npm install -g mint
```


```bash yarn
yarn global add mint
```


```bash pnpm
pnpm add -g mint
```
Expand All @@ -103,11 +100,13 @@
You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide.
</Info>

### Edit the Documentation
### Edit Your Documentation

Now that your environment is set up, you can start editing your documentation files. As an example, let's update the title of the introduction page:

Open your repository created during onboarding, find the `introduction.mdx` file, and find the top of the file, that should look like this:
1. Open your repository created during onboarding
2. Find the `introduction.mdx` file
3. Locate the frontmatter at the top of the file:

Check warning on line 109 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

quickstart.mdx#L109 

Did you really mean 'frontmatter'?

```jsx introduction.mdx
---
Expand All @@ -116,7 +115,7 @@
---
```

Update the `title` field to `"Hello World"`.
4. Update the `title` field to `"Hello World"`:

```jsx introduction.mdx {2}
---
Expand All @@ -125,28 +124,33 @@
---
```

### Preview the Changes
### Preview Your Changes

To preview the changes locally, run the following command.
To preview the changes locally, run the following command:

```bash
mint dev
```

Your preview will be available at `localhost:3000`.

<Frame>
<img src="/images/quickstart/mintlify-dev-light.png" alt="Mintlify Dev" className="block dark:hidden" />
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Mintlify Dev" className="hidden dark:block" />
<Frame caption="Local development server showing your documentation changes in real-time">
<img src="/images/quickstart/mintlify-dev-light.png" alt="Local development preview showing documentation site at localhost:3000" className="block dark:hidden" />
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Local development preview showing documentation site at localhost:3000 in dark mode" className="hidden dark:block" />
</Frame>

### Push the Changes
### Push Your Changes

When you're ready to publish your changes, simply push them to your repository.

When you're ready to publish your changes, simply push the changes to your repository.
The system will automatically:
- Detect the changes
- Build your documentation
- Deploy the updates to your site

Mintlify will automatically detect the changes, build your documentation, and deploy the updates to your site. You can monitor the deployment status in your GitHub repository's commit history or the [dashboard](https://dashboard.mintlify.com).
You can monitor the deployment status in your GitHub repository's commit history or the [dashboard](https://dashboard.mintlify.com).

Once the deployment is complete, your last update will be available at `<your-project-name>.mintlify.app`.
Once the deployment is complete, your updates will be available at `<your-project-name>.mintlify.app`.

<Card title="Jump to adding a custom domain" icon="arrow-down" href="#adding-a-custom-domain" horizontal>
Optionally skip the web editor workflow and jump to adding a custom domain.
Expand All @@ -158,29 +162,28 @@

### Access the Web Editor

1. Log in to your [Mintlify Dashboard](https://dashboard.mintlify.com).
2. Select **Editor** on the left sidebar.
1. Log in to your [dashboard](https://dashboard.mintlify.com)
2. Select **Editor** on the left sidebar

<Info>
If you haven't installed the GitHub App, you will be prompted to do so upon opening the web editor.
If you haven't installed the GitHub App, you'll be prompted to do so upon opening the web editor.
</Info>

<Frame>
<img alt="The Mintlify web editor in the visual editor mode" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
<img alt="The Mintlify web editor in the visual editor mode" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
<Frame caption="The web editor provides a visual interface for editing documentation">
<img alt="Web editor interface showing visual editing mode with sidebar navigation and content area" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
<img alt="Web editor interface showing visual editing mode with sidebar navigation and content area in dark mode" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
</Frame>

### Edit the Documentation
### Edit Your Documentation

In the web editor, you can navigate your documentation files in the sidebar. Let's update the introduction page.
In the web editor, you can navigate your documentation files in the sidebar. Let's update the introduction page:

Find and click on `introduction.mdx` in the file explorer.
1. Find and click on `introduction.mdx` in the file explorer
2. In the visual editor, update the title field to "Hello World"

Then, in the visual editor, update the title field to "Hello World".

<Frame>
<img alt="Editing in Web Editor" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
<img alt="Editing in Web Editor" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
<Frame caption="Editing content directly in the visual editor with real-time preview">
<img alt="Web editor showing the editing interface with introduction.mdx file open and title field being modified" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
<img alt="Web editor showing the editing interface with introduction.mdx file open and title field being modified in dark mode" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
</Frame>

<Tip>
Expand All @@ -189,7 +192,7 @@

### Publish Your Changes

When you're satisfied with your edits, click the `Publish` button in the top-right corner.
When you're satisfied with your edits, click the **Publish** button in the top-right corner.

Your changes will be deployed immediately to your documentation site.

Expand All @@ -199,14 +202,18 @@

While your `<your-project-name>.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation.

To add a custom domain, go to `Settings` > `Custom Domain` from the dashboard.
To add a custom domain:

1. Go to **Settings** > **Custom Domain** from the dashboard
2. Enter your domain (e.g., docs.yourcompany.com)
3. Follow the provided instructions to configure DNS settings with your domain provider

<Frame>
<img src="/images/quickstart/custom-domain-light.png" alt="Custom Domain" className="block dark:hidden" />
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom Domain" className="hidden dark:block" />
<Frame caption="Custom domain configuration in the dashboard settings">
<img src="/images/quickstart/custom-domain-light.png" alt="Custom domain settings page showing domain input field and DNS configuration instructions" className="block dark:hidden" />
<img src="/images/quickstart/custom-domain-dark.png" alt="Custom domain settings page showing domain input field and DNS configuration instructions in dark mode" className="hidden dark:block" />
</Frame>

Enter your domain (e.g., docs.yourcompany.com) and follow the provided instructions to configure DNS settings with your domain provider.
Configure your DNS settings with these values:

<Table>
| Record Type | Name | Value | TTL |
Expand All @@ -220,7 +227,7 @@

## Next Steps

Congratulations! You've successfully deployed your documentation site with Mintlify. Here are some suggested next steps to enhance your documentation:
Congratulations! You've successfully deployed your documentation site. Here are some suggested next steps to enhance your documentation:

<Card title="Customize Your Theme" icon="paintbrush" href="themes" horizontal>
Learn how to customize colors, fonts, and the overall appearance of your documentation site.
Expand All @@ -237,19 +244,18 @@

## Troubleshooting

If you encounter any issues during the setup process, check our common troubleshooting solutions:
If you encounter any issues during the setup process, check these common solutions:

<AccordionGroup>
<Accordion title="Local preview not working">
Make sure you have Node.js v19+ installed and that you're running the `mint dev` command from the directory containing your `docs.json` file.
</Accordion>
<Accordion title="Changes not reflecting on live site">
Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors.
Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the dashboard to ensure there are no build errors.
</Accordion>
<Accordion title="Custom domain not connecting">
Verify that your DNS records are set up correctly and allow sufficient time for DNS propagation (up to 48 hours). You can use tools like [DNSChecker](https://dnschecker.org) to verify your CNAME record.
</Accordion>
</AccordionGroup>


Need more help? [Contact our Support Team](https://mintlify.com/docs/support).