Skip to content

Quickstart: guide through the GitHub setup #709

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

Merged
merged 3 commits into from
May 15, 2025
+36 −22
Merged

Quickstart: guide through the GitHub setup #709

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bcc79dc
Guide through the GItHub auth flow
ethanpalm May 15, 2025
0ec6373
change `Development` to `Mintlify`
ethanpalm May 15, 2025
8e257a7
reviewer feedback
ethanpalm May 15, 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
58 changes: 36 additions & 22 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,37 @@

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.

## Development Workflows
### Install the GitHub App

Mintlify provides a GitHub App that 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.

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 t oconnect.

Check warning on line 43 in quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

quickstart.mdx#L43 

Did you really mean 'oconnect'?

<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>

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

Choose a reason for hiding this comment

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

oh this is great

</Info>

### Authorize your GitHub Account
Copy link
Member

Choose a reason for hiding this comment

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

just to note - authorizing is not required. it is purely for associating commits with the proper author if you're making edits through the web editor.

Copy link
Member

Choose a reason for hiding this comment

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

it might be worth taking it out of the quickstart and putting it elsewhere

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I can see a page on the Git flow and setting up GitHub being helpful especially for people who haven't done docs as code before. Would best practice be to authorize your account or would we ever not want people to authorize?

For now, most people probably use the quickstart to get set up and we've got some feedback that people don't know you need to authorize to have commits associated with authors, so including it here should help solve that


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.

<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.

Expand Down Expand Up @@ -73,23 +103,6 @@
You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide.
</Info>

### Install the GitHub App

Mintlify provides a GitHub App that 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 by navigating to `Settings` > `Organization` > `GitHub`.

Click `Install GitHub App`. 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>

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

### Edit the 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:
Expand Down Expand Up @@ -141,19 +154,20 @@

## Web Editor Workflow

The web editor workflow provides a WYSIWYG interface for creating and editing documentation without requiring local development tools. It's ideal for non-technical team members or for making quick updates.
The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. It's ideal for people who want to work in their web browser without additional local development tools.

### Access the Web Editor

Log in to your Mintlify Dashboard and select your project. Navigate to `Editor` on the left sidebar to open the web editor.
1. Log in to your [Mintlify 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.
</Info>

<Frame>
<img alt="Web Editor" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
<img alt="Web Editor" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
<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>

### Edit the Documentation
Expand Down