Skip to content

Simplify quickstart guide #2389

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 1 commit into from
+19 −108
Closed

Simplify quickstart guide #2389

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
127 changes: 19 additions & 108 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,32 @@
---
title: "Quickstart"
description: "Deploy your documentation site and make your first change."
keywords: ["quickstart", "deploy", "get started", "first steps"]
---

After you complete this guide, you'll have a live documentation site ready to customize and update.
Get your documentation site live in minutes.

## Before you begin
## Deploy your site

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 headline="Repository" 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>. You can use your own Git repository or a Mintlify-hosted repository.

Choose your repository approach.

<CardGroup cols={2}>
<Card title="Mintlify-hosted" icon="cloud">
Mintlify creates a private GitHub repository connected to your Mintlify deployment.

Choose this option if:
- You will only work in the web editor and don't want to use Git locally.
- You want to get started quickly without connecting a repository.
- You want Mintlify to manage your documentation repository for you.
</Card>

<Card title="Your own repository" icon="github">
Connect your own Git repository to your Mintlify deployment.

Choose this option if:
- You will work locally and want to sync to your remote repository.
- You already have a repository for your documentation.
- You want your documentation to be under your own GitHub organization.
</Card>
</CardGroup>

<Tip>
Not sure which to choose? Start with **Mintlify-hosted**. You can migrate to your own repository anytime if it better suits your needs.
</Tip>

## Deploy your documentation site

<Tabs>
<Tab title="Mintlify-hosted">
<Steps>
<Step title="Create your account">
Go to [mintlify.com/start](https://mintlify.com/start) and create your account.
</Step>
<Step title="Skip GitHub connection">
When prompted to connect GitHub, click **Skip** to use a Mintlify-hosted repository.
</Step>
<Step title="Complete onboarding">
Follow the onboarding prompts to set up your documentation. Mintlify automatically creates a private repository in the `mintlify-community` organization and configures the GitHub app for you.
</Step>
<Step title="Your site is deployed">
Your documentation is immediately deployed and accessible at your `.mintlify.app` URL.
</Step>
</Steps>
</Tab>

<Tab title="Your own repository">
<Steps>
<Step title="Create your account">
Go to [mintlify.com/start](https://mintlify.com/start) and create your account.
</Step>
<Step title="Connect GitHub">
When prompted, log in to your GitHub account and authenticate.
</Step>
<Step title="Complete onboarding">
Follow the remaining onboarding prompts to create a repository and continue to your dashboard.
</Step>
<Step title="Install the GitHub App">
Install the Mintlify [GitHub App](https://dashboard.mintlify.com/api/github/install-app) to enable automatic deployments. This allows Mintlify to sync with your repository and deploy changes automatically when you push.
</Step>
<Step title="Optional: Select a repository">
If you want to use a different repository than the one created during onboarding for your documentation, select it on the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard. Your documentation repository must have a valid `docs.json` file to deploy.
</Step>
<Step title="Your site is deployed">
Your documentation is deployed and accessible at your `.mintlify.app` URL. Future changes pushed to your repository will automatically trigger new deployments.
</Step>
</Steps>

<Info>
To learn more about the GitHub App and its permissions, see [GitHub](/deploy/github).
</Info>
</Tab>
</Tabs>

## View your deployed site

Your documentation site is now deployed at `https://<your-project-name>.mintlify.app`.

Find your exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/).

<Frame>
<img
src="/images/quickstart/mintlify-domain-light.png"
alt="Overview page of the Mintlify dashboard."
className="block dark:hidden"
/>

<img
src="/images/quickstart/mintlify-domain-dark.png"
alt="Overview page of the Mintlify dashboard."
className="hidden dark:block"
/>
</Frame>

<Tip>
Your site is ready to view immediately. Use this URL for testing and sharing with your team. Before sharing with your users, you may want to add a [custom domain](/customize/custom-domain).
</Tip>
<Steps>
<Step title="Create your account">
Go to [mintlify.com/start](https://mintlify.com/start) and sign up.
</Step>
<Step title="Complete setup">
Follow the onboarding prompts. You can connect your own GitHub repository or let Mintlify host one for you.
</Step>
<Step title="Your site is live">
Your documentation is deployed at `https://<your-project-name>.mintlify.app`.

Check warning on line 18 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L18 

In general, use active voice instead of passive voice ('is deployed').
</Step>
</Steps>

## Make your first change
## Make your first edit

<Steps>
<Step title="Open the web editor">
Navigate to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard.
Go to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard.
</Step>
<Step title="Edit a page">
Open `index.mdx` and update the description in the frontmatter:
Open `index.mdx` and change the description:

```mdx
---
Expand All @@ -125,14 +36,14 @@
```
</Step>
<Step title="Publish">
Click the **Publish** button in the top-right of the web editor toolbar.
Click **Publish** in the top-right corner.
</Step>
<Step title="View live">
On the [Overview](https://dashboard.mintlify.com/) page of your dashboard, you can see your site's deployment status. When it finishes deploying, refresh your documentation site to see your changes live.
<Step title="View your changes">
Refresh your site to see your changes live.
</Step>
</Steps>

## Next steps

Check warning on line 46 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L46 

'Next steps' should use sentence-style capitalization.

<CardGroup cols={3}>
<Card title="Learn about the web editor" icon="mouse-pointer-2" href="/editor">
Expand All @@ -140,7 +51,7 @@
</Card>

<Card title="Set up local development" icon="terminal" href="/installation">
Use the CLI to preview your documentation locally as you write and edit.

Check warning on line 54 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

quickstart.mdx#L54 

Use 'command-line tool' instead of 'CLI'.
</Card>

<Card title="Add a custom domain" icon="globe" href="/customize/custom-domain">
Expand Down