Skip to content

Improve quickstart page structure and UX #2839

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
mintlify wants to merge 2 commits into from
+24 −2
Closed

Improve quickstart page structure and UX #2839

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e476154
Update quickstart.mdx
mintlify[bot] Jan 23, 2026
e201f57
Update quickstart.mdx
mintlify[bot] Jan 23, 2026
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
26 changes: 24 additions & 2 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,31 @@
keywords: ["quickstart","deploy","get started","first steps"]
---

After you complete this guide, you'll have a live documentation site ready to customize and update.
<Info>**Time to complete:** ~5 minutes</Info>

## Before you begin
## What you'll build

By the end of this guide, you'll have a live documentation site like this:

<Frame>
<img
src="/images/quickstart/mintlify-domain-light.png"
alt="A deployed Mintlify documentation site."
className="block dark:hidden"
/>
<img
src="/images/quickstart/mintlify-domain-dark.png"
alt="A deployed Mintlify documentation site."
className="hidden dark:block"
/>
</Frame>

## Prerequisites

<Check>GitHub account</Check>
<Check>Node.js v20.17.0 or higher (for CLI usage)</Check>
Copy link

@cursor cursor bot Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong component used for prerequisites section

Low Severity

The <Check> component is used for the prerequisites list, but according to the component reference guidelines, <Check> is for "positive confirmations, successful completions, or achievement indicators" while <Info> is explicitly designated for "prerequisites, permissions, or required setup information." Using <Check> semantically implies these items have been completed rather than being requirements the user needs to have ready before starting.

Fix in Cursor Fix in Web


## How it works

Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation <Tooltip tip="Your documentation's source code where all files and their history are stored. The web editor connects to your documentation repository to access and modify content, or you can edit files locally in your preferred IDE.">repository</Tooltip>.

Expand All @@ -16,7 +38,7 @@

Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding process. During onboarding, you'll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments.

After onboarding, your documentation site is deployed and accessible at your `.mintlify.app` URL.

Check warning on line 41 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L41 

In general, use active voice instead of passive voice ('is deployed').

<AccordionGroup>
<Accordion title="Optional: Skip connecting GitHub during onboarding">
Expand Down Expand Up @@ -56,7 +78,7 @@
<Tab title="CLI">
<Steps>
<Step title="Install the CLI">
The CLI requires [Node.js](https://nodejs.org/en) v20.17.0 or higher. Use an LTS version for stability.

Check warning on line 81 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L81 

Spell out 'LTS', if it's unfamiliar to the audience.

<CodeGroup>

Expand Down Expand Up @@ -136,7 +158,7 @@
## Next steps

<Card title="Use the web editor" icon="mouse-pointer-2" horizontal href="/editor/index">
Edit documentation in your browser and preview how your pages will look when published.

Check warning on line 161 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L161 

Avoid using 'will'.
</Card>
<Card title="Explore CLI commands" icon="terminal" horizontal href="/installation#additional-commands">
Find broken links, check accessibility, validate OpenAPI specs, and more.
Expand Down
Loading