Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions deploy/authentication-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
2. Enable authentication.
3. In the **Password Protection** section, enter a secure password

After you enter a password, your site redploys. When it finishes deploying, anyone who visits your site must enter the password to access your content.
After you enter a password, your site redeploys. When it finishes deploying, anyone who visits your site must enter the password to access your content.
</Step>
<Step title="Distribute access.">
Securely share the password and documentation URL with authorized users.
Expand All @@ -45,9 +45,9 @@

### Example

Your host your documentation at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.
You host your documentation at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.

**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!

Check warning on line 50 in deploy/authentication-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/authentication-setup.mdx#L50

Don't use exclamation points in text.
</Tab>
<Tab title="Mintlify dashboard">
### Prerequisites
Expand All @@ -74,7 +74,7 @@

### Example

Your host your documentation at `docs.foo.com` and your entire team has access to your dashboard. You want to restrict access to team members only.
You host your documentation at `docs.foo.com` and your entire team has access to your dashboard. You want to restrict access to team members only.

**Enable Mintlify authentication** in your dashboard settings.

Expand Down Expand Up @@ -125,7 +125,7 @@

### Example

Your host your documentation at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.
You host your documentation at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.

**Configure your OAuth server details** in your dashboard:
- **Authorization URL**: `https://auth.foo.com/authorization`
Expand Down Expand Up @@ -186,7 +186,7 @@

### Example

Your host your documentation at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard).
You host your documentation at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard).

Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication.

Expand Down
4 changes: 2 additions & 2 deletions deploy/ghes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@

#### Firewall configuration

The following outbound connections must be allowed:

Check warning on line 27 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L27

In general, use active voice instead of passive voice ('be allowed').
- Connections from Mintlify's static IP: `54.242.90.151`
- HTTPS (port 443) to Mintlify's service domains

Check warning on line 29 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L29

Use 'https' instead of 'HTTPS'.
- DNS resolution for Mintlify's service domains

## Step 1: Register the GitHub App
Expand All @@ -36,7 +36,7 @@
<Steps>
<Step title="Navigate to your organization settings">
1. In the upper-right corner of any page on GitHub, click your profile picture.
2.Click **Your organizations**.
2. Click **Your organizations**.
3. Click **Settings** next to the organization that you want to create the app for.
</Step>

Expand All @@ -61,7 +61,7 @@

<Steps>
<Step title="Set repository permissions">
Set the following permissions for the app. No Organization, Account, or Enterprise permissions are required:

Check warning on line 64 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L64

In general, use active voice instead of passive voice ('are required').

- **Checks:** Read and write
- **Contents:** Read and write
Expand Down Expand Up @@ -90,7 +90,7 @@
<Step title="Create the app">
Click **Create GitHub App**.

You'll be redirected to the app's settings page.

Check warning on line 93 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L93

In general, use active voice instead of passive voice ('be redirected').
</Step>

<Step title="Generate private key">
Expand Down Expand Up @@ -123,7 +123,7 @@
- **Only select repositories** (choose specific repositories)

<Tip>
We reccomend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located.
We recommend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located.

Check warning on line 126 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L126

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

Expand All @@ -144,8 +144,8 @@
<Step title="Set webhook URL">
Configure the following:

- **Webhook URL:** `https://leaves.mintlify.com/github-enterprise/:subdomain` (replace `:subdomain` with the URL that we provide you with)

Check warning on line 147 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L147

Use 'webhook' instead of 'Webhook'.
- **Webhook secret:** Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you.

Check warning on line 148 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L148

Use 'webhook' instead of 'Webhook'.
</Step>
</Steps>

Expand All @@ -158,13 +158,13 @@
- App client ID: (from step 3)
- App client secret: (from step 3)
- Installation ID: (from step 4)
- Private key: The entire contents of the `.pem` file (should be shared via secure file transfer)

Check warning on line 161 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L161

In general, use active voice instead of passive voice ('be shared').
- Webhook secret: (from step 5)

Check warning on line 162 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L162

Use 'webhook' instead of 'Webhook'.

### Optional credentials for troubleshooting
- Organization name: Your GitHub organization name
- Repository names: Specific repositories where the app is installed

Check warning on line 166 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L166

In general, use active voice instead of passive voice ('is installed').
- GitHub Enterprise Server version: Found in your site admin dashboard

Check warning on line 167 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L167

Use 'administrator' instead of 'admin'.

## Mintlify connection
We take the credentials you provide us and store them, encrypted, in a secure location. Then we work with you to either:
Expand All @@ -172,7 +172,7 @@
- Integrate your GHES environment with an existing Mintlify deployment.
- Integrate your GHES environment with a new Mintlify deployment that we provision for you.

After your GHES environment is integrated with a Mintlify deployment, you are ready to enable webhooks for your GitHub App.

Check warning on line 175 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L175

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

<Note>
The webhook URL may change based on our configuration. We test the integration and provide you with the new URL.
Expand All @@ -185,7 +185,7 @@
1. Go to your GitHub App settings.
2. Click the **Advanced** tab.
2. Check "Recent Deliveries" for successful webhook deliveries.
3. Look for HTTP 200 responses.

Check warning on line 188 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L188

Use 'http' instead of 'HTTP'.
</Step>

<Step title="Test repository access">
Expand All @@ -194,33 +194,33 @@
</Step>
</Steps>

## FAQ and Troubleshooting

Check warning on line 197 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L197

'FAQ and Troubleshooting' should use sentence-style capitalization.

<AccordionGroup>
<Accordion title="The app installation is failing with permission errors.">
Ensure you have:

- Site admin privileges for app creation

Check warning on line 203 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L203

Use 'administrator' instead of 'admin'.
- Organization owner or admin rights for app installation.

Check warning on line 204 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L204

Use 'administrator' instead of 'admin'.
- Proper repository permissions if installing on specific repositories.
</Accordion>

<Accordion title="Webhooks aren't being delivered">
- Verify the webhook URL is correct and accessible.
- Ensure your firewall allows outbound HTTPS connections.

Check warning on line 210 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L210

Use 'https' instead of 'HTTPS'.
- Check the webhook secret matches what was configured.

Check warning on line 211 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L211

In general, use active voice instead of passive voice ('was configured').
- Review webhook delivery logs in the "Advanced" tab of your GitHub App settings.
</Accordion>

<Accordion title="I'm getting SSL/TLS certificate errors">
Your GHES might use self-signed certificates. Our services cannot verify your server's certificate.

**Solution:** Ensure your GHES has a valid SSL certificate.

Check warning on line 218 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L218

Use 'ssl' instead of 'SSL'.
</Accordion>

<Accordion title="The app installs, but doesn't respond to events.">
- Ensure webhooks are being delivered and acknowledged by our server with response code 200.

Check warning on line 222 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L222

In general, use active voice instead of passive voice ('being delivered').
- Required permissions were granted during installation.

Check warning on line 223 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L223

In general, use active voice instead of passive voice ('were granted').
</Accordion>

<Accordion title="Can I limit which repositories the app accesses?">
Expand All @@ -228,17 +228,17 @@
</Accordion>

<Accordion title="How do I update app permissions later?">
- Go to the app settings as a site admin.

Check warning on line 231 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L231

Use 'administrator' instead of 'admin'.
- Modify permissions as needed.
- The app will need to be re-approved by organization owners.

Check warning on line 233 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L233

Avoid using 'will'.
- Notify us of any permission changes as they may affect functionality.

Check warning on line 234 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L234

Use 'capability' or 'feature' instead of 'functionality'.
</Accordion>

<Accordion title="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
You must:

- Whitelist our service domains in your firewall.
- Ensure outbound HTTPS (port 443) connectivity.

Check warning on line 241 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L241

Use 'https' instead of 'HTTPS'.
- If direct internet access is not allowed, set up a proxy.
</Accordion>

Expand Down
2 changes: 1 addition & 1 deletion deploy/route53-cloudfront.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
Route traffic to this path with a Cache Policy of **CachingEnabled**:

- `/mintlify-assets/_next/static/*`
- `Default (*)` - Your websites landing page
- `Default (*)` - Your website's landing page

All Behaviors must have the an **origin request policy** of `AllViewerExceptHostHeader`.

Expand All @@ -39,7 +39,7 @@
3. For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is your project's unique subdomain.

<Frame>
![CloudFront "Create distribution" page showing "acme.mintlify.dev" as the origin domain.](/images/cloudfront/origin-name.png)

Check warning on line 42 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L42

Use 'Dev' instead of 'dev'.
</Frame>

4. For "Web Application Firewall (WAF)," enable security protections.
Expand All @@ -59,10 +59,10 @@
![A CloudFront distribution with the "Origins" tab highlighted.](/images/cloudfront/origins.png)
</Frame>

2. Find your staging URL that mirrors the main domain. This is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app).

Check warning on line 62 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L62

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

<Info>
If your landing page is hosted on Webflow, use Webflow's staging URL. It would look like `.webflow.io`.

Check warning on line 65 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L65

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

If you use Vercel, use the `.vercel.app` domain available for every project.
</Info>
Expand Down Expand Up @@ -105,7 +105,7 @@
</Frame>

<Info>
If `.well-known/*` is too generic, it can be narrowed down to 2 behaviors at a minimum for Vercel:

Check warning on line 108 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L108

In general, use active voice instead of passive voice ('be narrowed').
- `/.well-known/vercel/*` - Required for Vercel domain verification
- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
</Info>
Expand All @@ -116,10 +116,10 @@

- Set "Cache policy" to **CachingOptimized**.
- Set "Origin request policy" to **AllViewerExceptHostHeader**.
- Set Viewer Protocol Policy to **Redirect HTTP to HTTPS**

Check warning on line 119 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L119

Use 'http' instead of 'HTTP'.

Check warning on line 119 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L119

Use 'https' instead of 'HTTPS'.

<Frame>
![CloudFront "Create behavior" page with a "Path pattern" of "/docs/*" and "Origin and origin groups" pointing to the `acme.mintlify.dev` URL.](/images/cloudfront/behavior-1.png)

Check warning on line 122 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L122

Use 'Dev' instead of 'dev'.
</Frame>

### Your subpath with wildcard
Expand All @@ -130,13 +130,13 @@

- Set "Cache policy" to **CachingOptimized**.
- Set "Origin request policy" to **AllViewerExceptHostHeader**.
- Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**

Check warning on line 133 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L133

Use 'http' instead of 'HTTP'.

Check warning on line 133 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L133

Use 'https' instead of 'HTTPS'.

### `/mintlify-assets/_next/static/*`

- Set "Cache policy" to **CachingOptimized**
- Set "Origin request policy" to **AllViewerExceptHostHeader**
- Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**

Check warning on line 139 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L139

Use 'http' instead of 'HTTP'.

Check warning on line 139 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L139

Use 'https' instead of 'HTTPS'.

### `Default (*)`

Expand All @@ -154,9 +154,9 @@

2. Select **Save changes**.

### Check behaviors are set up correctly

Check warning on line 157 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L157

In general, use active voice instead of passive voice ('are set').

If you follow the above steps, your behaviors should look like this:

Check warning on line 159 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L159

Use 'preceding' instead of 'above'.

<Frame>
![CloudFront "Behaviors" page with 4 behaviors: `/docs/*`, `/docs`, `Default`, and `/.well-known/*`.](/images/cloudfront/all-behaviors.png)
Expand All @@ -164,7 +164,7 @@

## Preview distribution

You can now test if your distribution is set up properly by going to the "General" tab and visiting the **Distribution domain name** URL.

Check warning on line 167 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L167

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

<Frame>
![CloudFront "General" tab with the "Distribution domain name" URL highlighted.](/images/cloudfront/preview-distribution.png)
Expand All @@ -172,9 +172,9 @@

All pages should be directing to your main landing page, but if you append your chosen subpath, for example `/docs`, to the URL, you should see it going to your Mintlify documentation instance.

## Connect with Route53

Check warning on line 175 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L175

'Connect with Route53' should use sentence-style capitalization.

Now, we're going to bring the functionality of the CloudFront distribution into your primary domain.

Check warning on line 177 in deploy/route53-cloudfront.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/route53-cloudfront.mdx#L177

Use 'capability' or 'feature' instead of 'functionality'.

<Note>
For this section, you can also refer to AWS's official guide on [Configuring
Expand Down