Skip to content

docs: align voice and tone with style guide #5841

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

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −8
Open

docs: align voice and tone with style guide #5841

Show file tree
Hide file tree
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
2 changes: 1 addition & 1 deletion customize/custom-scripts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@
- `#content-area` — Primary content area, excluding the sidebar and table of contents.
- `#content` — Inner content element within the content area.
- `#header` — Page-level header element.
- `#banner` — Announcement banner displayed above the navbar.

Check warning on line 67 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L67 

Use 'preceding' instead of 'above'.
- `#footer` — Page footer. Also targetable as an element selector: `footer`.
- `#page-title` — The `<h1>` heading at the top of each page.
- `#pagination` — Bottom pagination bar with previous and next page links.
Expand All @@ -79,12 +79,12 @@
</Accordion>
<Accordion title="Sidebar">
- `#sidebar` — The sidebar navigation panel.
- `#sidebar-content` — Scrollable content area within the sidebar.

Check warning on line 82 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L82 

Did you really mean 'Scrollable'?
</Accordion>
<Accordion title="Table of contents">
- `#table-of-contents` — Table of contents panel on the right side of the page.
- `#table-of-contents-layout` — Layout wrapper for the table of contents.
- `#table-of-contents-content` — Scrollable content within the table of contents.

Check warning on line 87 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L87 

Did you really mean 'Scrollable'?
</Accordion>
<Accordion title="Search">
- `#search-bar-entry` — Search bar trigger in the topbar.
Expand Down Expand Up @@ -122,7 +122,7 @@
</Accordion>
<Accordion title="Localization">
- `#localization-select-trigger` — Button that opens the language selector.
- `#localization-select-content` — Dropdown content of the language selector.

Check warning on line 125 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L125 

Use 'dropdowns?' instead of 'Dropdown'.
- `#localization-select-item` — Individual language option within the selector.
</Accordion>
<Accordion title="Changelog">
Expand All @@ -130,10 +130,10 @@
- `#changelog-filters-content` — Content area within the changelog filter panel.
</Accordion>
<Accordion title="Multi-view">
- `#multi-view-dropdown` — Dropdown for switching between documentation views.

Check warning on line 133 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L133 

Use 'dropdowns?' instead of 'Dropdown'.
</Accordion>
<Accordion title="Text selection">
- `#text-selection-tooltip` — Tooltip that appears when text is selected on a page.

Check warning on line 136 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L136 

In general, use active voice instead of passive voice ('is selected').
- `#text-selection-tooltip-button` — Action button within the text selection tooltip.
</Accordion>
</AccordionGroup>
Expand All @@ -146,7 +146,7 @@
<Accordion title="Content components">
- `accordion` — Collapsible accordion item.
- `accordion-group` — Wrapper grouping multiple accordions.
- `callout` — Callout block (Note, Warning, Tip, etc.).

Check warning on line 149 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L149 

Use 'callouts?' instead of 'Callout'.
- `card` — Individual card element.
- `card-group` — Wrapper grouping multiple cards. Deprecated in favor of `columns`, but preserved for backward compatibility.
- `columns` — Multi-column layout wrapper.
Expand All @@ -168,9 +168,9 @@
<Accordion title="Page layout">
- `mdx-content` — Rendered MDX content area.
- `panel` — Floating panel component. Also targetable as an ID selector: `#panel`.
- `eyebrow` — Small label displayed above a page title.

Check warning on line 171 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L171 

Use 'preceding' instead of 'above'.
- `link` — Anchor link element.
- `breadcrumb-list` — Breadcrumb navigation list.

Check warning on line 173 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L173 

Use 'breadcrumbs?' instead of 'Breadcrumb'.
- `breadcrumb-item` — Individual breadcrumb item.
</Accordion>
<Accordion title="Topbar navigation">
Expand Down Expand Up @@ -228,7 +228,7 @@
- `api-section-heading-title` — Title within an API endpoint section heading.
- `api-section-heading-subtitle` — Subtitle within an API endpoint section heading.
- `field` — Parameter or property field in the API reference.
- `option-dropdown` — Dropdown for selecting between API options.

Check warning on line 231 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L231 

Use 'dropdowns?' instead of 'Dropdown'.
- `tryit-button` — "Try it" button that opens the API playground.
- `method-pill` — HTTP method badge (GET, POST, etc.) on an endpoint.
- `method-nav-pill` — HTTP method badge shown in the sidebar navigation.
Expand All @@ -255,7 +255,7 @@
- `contextual-feedback-form-submit-button` — Submit button for the contextual feedback form.
</Accordion>
<Accordion title="Code snippet feedback">
- `code-snippet-feedback-popover-content` — Popover content for code snippet feedback.

Check warning on line 258 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L258 

Use 'popovers?' instead of 'Popover'.
- `code-snippet-feedback-form` — Feedback form for a code snippet.
- `code-snippet-feedback-textarea` — Text area within the code snippet feedback form.
- `code-snippet-feedback-form-title` — Title of the code snippet feedback form.
Expand All @@ -268,7 +268,7 @@
</Accordion>
<Accordion title="Multi-view">
- `multi-view-item` — Individual view option in a multi-view switcher.
- `multi-view-dropdown` — Dropdown for selecting between multiple views.

Check warning on line 271 in customize/custom-scripts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-scripts.mdx#L271 

Use 'dropdowns?' instead of 'Dropdown'.
- `multi-view-dropdown-trigger` — Button that opens the multi-view dropdown.
- `multi-view-dropdown-content` — Content area of the multi-view dropdown.
- `multi-view-dropdown-item` — Individual item within the multi-view dropdown.
Expand Down Expand Up @@ -360,5 +360,5 @@
```

<Warning>
Please use with caution to not introduce security vulnerabilities.
Use with caution to avoid introducing security vulnerabilities.
</Warning>
4 changes: 2 additions & 2 deletions deploy/ghes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

#### 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
- DNS resolution for Mintlify's service domains
Expand Down Expand Up @@ -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 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 @@ -150,7 +150,7 @@
</Steps>

## Share credentials with us
Please share the following information with our team using your secure information transfer method of choice.
Share the following information with our team using your secure information transfer method of choice.

### Required credentials
- GitHub Enterprise Server base URL: https://your-github-server.com
Expand All @@ -158,12 +158,12 @@
- 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)

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

## Mintlify connection
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 Down Expand Up @@ -208,7 +208,7 @@
<Accordion title="Webhooks aren't being delivered">
- Verify the webhook URL is correct and accessible.
- Ensure your firewall allows outbound HTTPS connections.
- 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>

Expand All @@ -219,8 +219,8 @@
</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 @@ -231,7 +231,7 @@
- Go to the app settings as a site admin.
- Modify permissions as needed.
- The app needs to be re-approved by organization owners.
- Notify us of any permission changes so we can advise on any additional steps that may be required.

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 

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

<Accordion title="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
Expand All @@ -247,7 +247,7 @@
</Accordion>

<Accordion title="Who should I contact if I need help?">
Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at <a href="mailto:support@mintlify.com">support@mintlify.com</a> with:
Reach out to your customer success representative at Mintlify, or contact our support team at <a href="mailto:support@mintlify.com">support@mintlify.com</a> with:

- Your GitHub Enterprise Server version.
- Specific error messages.
Expand Down
10 changes: 5 additions & 5 deletions deploy/route53-cloudfront.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 varies 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 All @@ -81,7 +81,7 @@

## Set behaviors

Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic:
Behaviors in CloudFront enable control over the subpath logic. At a high level, you create the following logic:

- **If a user lands on your custom subpath**, go to `[SUBDOMAIN].mintlify.dev`.
- **If a user lands on any other page**, go to the current landing page.
Expand All @@ -105,21 +105,21 @@
</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>

### Your subpath

Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing to the `.mintlify.dev` URL (for example, `acme.mintlify.dev`).

- Set "Cache policy" to **CachingOptimized**.
- Set "Origin request policy" to **AllViewerExceptHostHeader**.
- Set Viewer Protocol Policy to **Redirect HTTP to 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 @@ -140,13 +140,13 @@

### `Default (*)`

Lastly, we're going to edit the `Default (*)` behavior.
Lastly, edit the `Default (*)` behavior.

<Frame>
![A CloudFront distribution with the "Default (*)" behavior selected and the Edit button emphasized.](/images/cloudfront/default-behavior-1.png)
</Frame>

1. Change the default behavior's **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`).
1. Change the default behavior's **Origin and origin groups** to the staging URL (for example, `mintlify-landing-page.vercel.app`).

<Frame>
![CloudFront "Edit behavior" page with the "Origin and origin groups" input field highlighted.](/images/cloudfront/default-behavior-2.png)
Expand All @@ -154,7 +154,7 @@

2. Click **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 preceding steps, your behaviors should look like this:

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

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 Route 53' should use sentence-style capitalization.

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

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