Skip to content
Open
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
30 changes: 28 additions & 2 deletions customize/custom-domain.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,35 @@

### Apex domains

If you host your documentation at an apex domain like `example.com` with no subdomain, your DNS provider must support CNAME flattening or a virtual record type like `ALIAS` or `ANAME`. Standard DNS does not allow a `CNAME` record at the apex of a domain, so providers without this support cannot create the record shown in your dashboard.
If you host your documentation at an apex domain like `example.com` with no subdomain, you have two options:

Providers that support apex `CNAME` records include Cloudflare (CNAME flattening), Amazon Route 53 (alias records), DNSimple (`ALIAS` records), and Porkbun (`ALIAS` records). If your provider does not support any of these, host your documentation at a subdomain like `docs.example.com` instead.
- Use CNAME flattening or a virtual record type like `ALIAS` or `ANAME` on providers that support it.
- Use `A` and `AAAA` records that point directly to Mintlify's edge.

Standard DNS does not allow a `CNAME` record at the apex of a domain, so providers without flattening or `ALIAS`/`ANAME` support cannot create the record shown in your dashboard.

#### CNAME flattening or ALIAS records

Check warning on line 90 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L90

Spell out 'ALIAS', if it's unfamiliar to the audience.

Providers that support apex `CNAME` records include Cloudflare (CNAME flattening), Amazon Route 53 (alias records), DNSimple (`ALIAS` records), and Porkbun (`ALIAS` records). On these providers, create the record shown in your dashboard as-is and the provider resolves it to Mintlify's edge automatically.

#### A and AAAA records

Check warning on line 94 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L94

'A and AAAA records' should use sentence-style capitalization.

Check warning on line 94 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L94

Spell out 'AAAA', if it's unfamiliar to the audience.

If your provider does not support CNAME flattening or `ALIAS`/`ANAME` records, point your apex domain at Mintlify's edge with the following `A` and `AAAA` records instead of the `CNAME` shown in your dashboard:

```text
A | <your-domain> | 162.159.143.13
A | <your-domain> | 172.66.3.9
AAAA | <your-domain> | 2606:4700:7::2fd
AAAA | <your-domain> | 2a06:98c1:58::2fd
```

Add all four records. Keep the verification `TXT` records from your dashboard in place — they are still required for domain verification and TLS certificate issuance.

Check warning on line 105 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L105

Don't put a space before or after a dash.

<Note>
The `CNAME` and `A`/`AAAA` approaches are mutually exclusive. If you use the `A` and `AAAA` records above, do not also create a `CNAME` for the same hostname.

Check warning on line 108 in customize/custom-domain.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/custom-domain.mdx#L108

Use 'preceding' instead of 'above'.
</Note>

If you would rather not manage apex records, host your documentation at a subdomain like `docs.example.com` and redirect the apex to it at your DNS provider or CDN.

### DNS propagation

Expand Down