Rewrite Quickstart page with richer MDX structure #5608
+106
−96
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,32 @@ | ||
| --- | ||
| title: "Quickstart" | ||
| description: "Get started with Mintlify by deploying your documentation site in minutes and making your first content change with the web editor or Git." | ||
| keywords: ["quickstart", "deploy", "get started", "first steps", "tutorial", "setup", "onboarding"] | ||
| --- | ||
|
|
||
| By the end of this guide, you'll have a live documentation site deployed and your first content change published. | ||
|
|
||
| ## How Mintlify works | ||
|
|
||
| Mintlify uses a docs-as-code approach. Every page on your site is a file — usually MDX — stored in a <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.">Git repository</Tooltip>. When you push a change to that repository, Mintlify automatically rebuilds and deploys your site. | ||
|
Check warning on line 11 in quickstart.mdx
|
||
|
|
||
| You can edit documentation two ways: | ||
|
|
||
| <CardGroup cols={2}> | ||
| <Card title="Web editor" icon="mouse-pointer-2" href="/editor/index"> | ||
| Edit in your browser — no local setup required. Changes publish directly to Git. | ||
| </Card> | ||
|
|
||
| <Card title="CLI + local editor" icon="terminal" href="/cli/install"> | ||
| Clone your repo, preview locally with `mint dev`, and push to deploy. | ||
| </Card> | ||
| </CardGroup> | ||
|
|
||
| <Tip> | ||
| **Using an AI coding tool?** Add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your docs. | ||
| </Tip> | ||
|
|
||
| <Prompt description="Install the Mintlify skill to get context on Mintlify project structure, components, and documentation best practices:\\n\\nnpx skills add https://mintlify.com/docs\\n\\nThen add the Mintlify MCP server for access to documentation search. Follow the setup instructions at https://www.mintlify.com/docs/ai/model-context-protocol.md" actions={["copy", "cursor"]}> | ||
| Install the Mintlify skill to get context on Mintlify project structure, components, and documentation best practices: | ||
|
|
||
| npx skills add https://mintlify.com/docs | ||
|
|
@@ -32,45 +36,76 @@ | |
|
|
||
| ## Deploy your documentation site | ||
|
|
||
| <Steps> | ||
| <Step title="Create your project"> | ||
| Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding flow. You'll connect your GitHub account, select or create a repository, and install the GitHub App. | ||
|
|
||
| <AccordionGroup> | ||
| <Accordion title="Want to skip connecting a Git provider for now?"> | ||
| During onboarding, you can skip the GitHub step. Mintlify will create a private repository under a managed organization and configure everything automatically — you can start using the web editor immediately. | ||
|
|
||
| When you're ready to move to your own repo, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard and use the Git setup wizard. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository) for details. | ||
| </Accordion> | ||
| </AccordionGroup> | ||
| </Step> | ||
| <Step title="View your live site"> | ||
| After onboarding, your site deploys to `https://<your-project-name>.mintlify.app`. | ||
|
|
||
| Find the exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/). | ||
|
|
||
| <Frame> | ||
| <img | ||
| alt="Overview page of the Mintlify dashboard." | ||
| className="block dark:hidden" | ||
| src="/images/quickstart/mintlify-domain-light.png" | ||
| /> | ||
| <img | ||
| alt="Overview page of the Mintlify dashboard." | ||
| className="hidden dark:block" | ||
| src="/images/quickstart/mintlify-domain-dark.png" | ||
| /> | ||
| </Frame> | ||
|
|
||
| <Tip> | ||
| This URL is live immediately. Share it with your team for testing. When you're ready to go public, [add a custom domain](/customize/custom-domain). | ||
| </Tip> | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Make your first change | ||
|
|
||
| Choose your preferred workflow: | ||
|
|
||
| <Tabs> | ||
| <Tab title="Web editor"> | ||
| <Steps> | ||
| <Step title="Open the web editor"> | ||
| Go to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard. | ||
| </Step> | ||
| <Step title="Edit a page"> | ||
| Open the **Introduction** page and update the description field. | ||
|
|
||
| <Frame> | ||
| <img | ||
| alt="Introduction page open in the web editor with the description edited to say Hello world!." | ||
| className="block dark:hidden" | ||
| src="/images/quickstart/hello-world-light.png" | ||
| /> | ||
| <img | ||
| alt="Introduction page open in the web editor with the description edited to say Hello world!." | ||
| className="hidden dark:block" | ||
| src="/images/quickstart/hello-world-dark.png" | ||
| /> | ||
| </Frame> | ||
| </Step> | ||
| <Step title="Publish"> | ||
| Click **Publish** in the top-right of the editor toolbar. The editor commits your change to Git and triggers a deployment. | ||
| </Step> | ||
| <Step title="Check deployment status"> | ||
| On the [Overview](https://dashboard.mintlify.com/) page of your dashboard, watch the deployment status. Refresh your documentation site once it finishes to see your change live. | ||
| </Step> | ||
| </Steps> | ||
| </Tab> | ||
| <Tab title="CLI"> | ||
| <Steps> | ||
| <Step title="Install the CLI"> | ||
|
|
@@ -82,20 +117,19 @@ | |
| npm i -g mint | ||
| ``` | ||
|
|
||
| ```bash pnpm | ||
| pnpm add -g mint | ||
| ``` | ||
|
|
||
| </CodeGroup> | ||
|
|
||
| See [Install the CLI](/cli/install) for troubleshooting and full details. | ||
| </Step> | ||
| <Step title="Clone your repository"> | ||
| If you haven't cloned your docs repo locally yet, follow the steps in [Clone your repository](/cli/install#clone-your-repository). | ||
| </Step> | ||
| <Step title="Edit a page"> | ||
| Open `index.mdx` in your editor and change the description in the frontmatter: | ||
|
|
||
| ```mdx | ||
| --- | ||
|
|
@@ -105,69 +139,45 @@ | |
| ``` | ||
| </Step> | ||
| <Step title="Preview locally"> | ||
| From your documentation directory, run: | ||
|
|
||
| ```bash | ||
| mint dev | ||
| ``` | ||
|
|
||
| View your changes at `http://localhost:3000` before pushing. | ||
| </Step> | ||
| <Step title="Push to deploy"> | ||
| Commit and push to trigger a deployment: | ||
|
|
||
| ```bash | ||
| git add . | ||
| git commit -m "Update description" | ||
| git push | ||
| ``` | ||
|
|
||
| Mintlify deploys automatically. Track the status on your [dashboard Overview](https://dashboard.mintlify.com/). | ||
| </Step> | ||
| </Steps> | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| ## Next steps | ||
|
|
||
| <CardGroup cols={2}> | ||
| <Card title="Use the web editor" icon="mouse-pointer-2" href="/editor/index"> | ||
| Edit, preview, and publish documentation directly in your browser. | ||
| </Card> | ||
|
|
||
| <Card title="Explore CLI commands" icon="terminal" href="/cli/index"> | ||
| Find broken links, check accessibility, validate OpenAPI specs, and more. | ||
| </Card> | ||
|
|
||
| <Card title="Add a custom domain" icon="globe" href="/customize/custom-domain"> | ||
| Swap your `.mintlify.app` URL for your own domain. | ||
| </Card> | ||
|
|
||
| <Card title="Customize your site" icon="paintbrush" href="/customize/overview"> | ||
| Configure branding, navigation, colors, and page layouts. | ||
|
There was a problem hiding this comment. Broken link to nonexistent customize/overview pageHigh Severity The newly added "Customize your site" card links to   Reviewed by Cursor Bugbot for commit a766137. Configure here. |
||
| </Card> | ||
| </CardGroup> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Escaped newlines render as literal backslash-n text
Medium Severity
The
Promptcomponent'sdescriptionprop uses\\n\\nto represent newlines, but in JSX string attributes\\nproduces a literal backslash followed by the letter 'n' — not a newline character. The prompt card will display raw\ntext between sentences instead of line breaks. The original used actual multi-line attribute values which preserved real newlines.Reviewed by Cursor Bugbot for commit a766137. Configure here.