diff --git a/quickstart.mdx b/quickstart.mdx index 48b44c8c..7c5e7557 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,8 +4,6 @@ description: "Deploy your documentation in minutes" 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. @@ -16,7 +14,7 @@ By the end of this guide, you'll have a live documentation site that's ready to ## 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://.mintlify.app @@ -24,38 +22,39 @@ https://.mintlify.app You can find your URL from the Overview page of the dashboard. - - Mintlify Domain - Mintlify Domain + + Dashboard overview showing the unique documentation URL with project name + Dashboard overview showing the unique documentation URL with project name in dark mode -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 - - GitHub App Installation - GitHub App Installation + + GitHub App installation page showing organization and repository selection options + GitHub App installation page showing organization and repository selection options in dark mode Remember to update the GitHub App permissions if you move the documentation to a different repository. -### 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) You may need an admin for your GitHub organization to authorize your account depending on your organization's settings. @@ -63,7 +62,7 @@ You can install the GitHub App by following the instructions from the onboarding ## Editing Workflows -Mintlify offers two different workflows for creating and maintaining your documentation. +Choose between two workflows for creating and maintaining your documentation: For developers who prefer working with their existing tools. Click to jump to section. @@ -87,12 +86,10 @@ To work locally with your documentation, install the Command Line Interface (CLI npm install -g mint ``` - ```bash yarn yarn global add mint ``` - ```bash pnpm pnpm add -g mint ``` @@ -103,11 +100,13 @@ pnpm add -g mint You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide. -### 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: ```jsx introduction.mdx --- @@ -116,7 +115,7 @@ description: "This is the introduction to the documentation" --- ``` -Update the `title` field to `"Hello World"`. +4. Update the `title` field to `"Hello World"`: ```jsx introduction.mdx {2} --- @@ -125,9 +124,9 @@ description: "This is the introduction to the documentation" --- ``` -### 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 @@ -135,18 +134,23 @@ mint dev Your preview will be available at `localhost:3000`. - - Mintlify Dev - Mintlify Dev + + Local development preview showing documentation site at localhost:3000 + Local development preview showing documentation site at localhost:3000 in dark mode -### 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 `.mintlify.app`. +Once the deployment is complete, your updates will be available at `.mintlify.app`. Optionally skip the web editor workflow and jump to adding a custom domain. @@ -158,29 +162,28 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf ### 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 - 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. - - The Mintlify web editor in the visual editor mode - The Mintlify web editor in the visual editor mode + + Web editor interface showing visual editing mode with sidebar navigation and content area + Web editor interface showing visual editing mode with sidebar navigation and content area in dark mode -### 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". - - - Editing in Web Editor - Editing in Web Editor + + Web editor showing the editing interface with introduction.mdx file open and title field being modified + Web editor showing the editing interface with introduction.mdx file open and title field being modified in dark mode @@ -189,7 +192,7 @@ Then, in the visual editor, update the title field to "Hello World". ### 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. @@ -199,14 +202,18 @@ For more details about using the web editor, including advanced features like sl While your `.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 - - Custom Domain - Custom Domain + + Custom domain settings page showing domain input field and DNS configuration instructions + Custom domain settings page showing domain input field and DNS configuration instructions in dark mode -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: | Record Type | Name | Value | TTL | @@ -220,7 +227,7 @@ Enter your domain (e.g., docs.yourcompany.com) and follow the provided instructi ## 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: Learn how to customize colors, fonts, and the overall appearance of your documentation site. @@ -237,19 +244,18 @@ Congratulations! You've successfully deployed your documentation site with Mintl ## 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: 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. - 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. 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. - Need more help? [Contact our Support Team](https://mintlify.com/docs/support). \ No newline at end of file