Custom domain lifecycle

Understand the custom-domain lifecycle

A custom domain is your own web address for serving published documentation, such as docs.yourcompany.com. The setup stages are Waiting for DNS, Verifying, Issuing certificate, and Live. The other outcomes are Verification failed, Certificate failed, Offline, and Removed.

The lifecycle starts when the domain is connected and DNS records are checked.

mermaid
stateDiagram-v2
    state "Waiting for DNS" as s1
    state "Verifying" as s2
    state "Issuing certificate" as s3
    state "Live" as s4
    state "Verification failed" as s5
    state "Certificate failed" as s6
    state "Offline" as s7
    state "Removed" as s8
    s1 --> s2: Check now
    s2 --> s3: Check now
    s3 --> s4: Check now
    s5 --> s2: Retry
    s6 --> s2: Retry
    s7 --> s2: Recover
    s4 --> s7: Check now
    s4 --> s8: Remove domain
    s8 --> s1: Connect domain

If you need to…	Go to
Connect a domain or change a subdomain	Manage custom domains
Open the settings area that contains the Domain tab	Configure Branding
Understand the full status path	Continue with Check DNS and respond to the status
Find the next action for a displayed status	Handle each domain-status branch

Before you start

Prerequisites

Select the project whose published documentation uses the domain.
Have access to the DNS provider for the domain. DNS records are the type, name, and value that the Domain surface displays for the domain.
Know whether you are checking an existing domain or connecting one for the first time.
Keep the domain's current status and last check time in view when deciding what to do next.
Use the exact message shown on screen when a check, retry, or removal does not complete.

The domain surface does not mark its visible controls as required. The page displays the current domain value, DNS values, registrar, last-check value, and current status when available.

Open the domain status

The Domain tab is the project-level surface for reading and responding to a custom-domain status. Use Manage custom domains when you need to connect or change an address.

Prerequisites

You have selected a project.

Steps

Open Branding settings for the selected project.
Select Domain.

Select Domain to view the project's subdomain and custom-domain status controls.

Result: The Domain tab opens with the Subdomain and Custom domain surfaces.

Read the status surface

The Domain tab puts the project's published-address settings and custom-domain status together. The Subdomain card contains Current address and Rename subdomain. The Custom domain card contains the domain value and, when a domain is being managed, its DNS records and status actions.

The visible status information is organised as follows:

What you need to read	Where to read it
The configured address	The value beside Custom domain
The records to add or inspect	DNS records
The record kind	Type
The DNS name	Name
The required DNS value	Value
Whether a record check succeeded	Status
The last check time	Last checked
A server-side reason for a failed or Offline state	Last error:

The surface can show Check now, Retry, or Recover according to the current status. When the domain is live, it shows Open beside the live address. Remove domain is in the danger area. Copy controls are available beside the domain and DNS-record values.

Check DNS and respond to the status

DNS checking compares the domain's configured records with the records listed in DNS records. The check can move the domain through its lifecycle, and the available action changes when the status changes.

Prerequisites

The Domain tab is open.
A custom domain is present in the management panel.

Steps

Read the expected entries in DNS records.
Select Check now.
Choose the action that matches the status shown:

If the status is… Select…
Verification failed or Certificate failed Retry
Offline Recover
Live Open to open the live documentation address
Read Type, Name, Value, and Status again after the check.

If the status is…	Select…
Verification failed or Certificate failed	Retry
Offline	Recover
Live	Open to open the live documentation address

Result: The panel shows the latest DNS check and the action that applies to the current domain status.

Handle each domain-status branch

Each status tells you what is happening to the custom domain and which next action belongs to it. Use the status chip and the DNS records table together; the DNS table shows the values that need attention when a check does not succeed.

Prerequisites

The Domain tab is open.
The custom-domain status is visible.

Steps

Read the status chip and follow the matching branch:

Status shown	What it means for your next move
Waiting for DNS	Add or correct the listed DNS records, then use Check now.
Verifying	Wait for the DNS check to finish and review the displayed records.
Issuing certificate	Wait for certificate issuance, then review the status again.
Live	Select Open when you need to view the published documentation.
Verification failed	Correct the DNS records and select Retry.
Certificate failed	Select Retry after the certificate problem is ready to be retried.
Offline	Restore the DNS records and select Recover.
Removed	Reconnect the domain from the setup surface with Connect domain.

Result: You have taken the action associated with the displayed status, or the status remains visible with the DNS information needed for the next check.

When a check or removal goes wrong

Use the exact message on screen to identify the correction.

Prerequisites

The Domain tab is open.
The message is visible in the domain surface.

Steps

Read the exact message shown in the domain surface.
Apply the action in the matching row below.

What you see	What to do
`Enter a valid domain, like docs.yourcompany.com`	Enter a domain in the requested format.
`Apex domains need ALIAS-capable DNS — we recommend a subdomain like docs.yourcompany.com`	Review the apex-domain warning before continuing.
`Could not load your domain settings.`	Select Try again.
`Try again`	Select Try again to retry loading the domain settings.
`Observed:`	Compare this value with the expected value in the same DNS-record row.
`nothing yet`	Add the listed DNS record, then select Check now.
`Open DNS settings`	Select Open DNS settings when the link is available.
`Your docs are live at`	Select Open to open the live documentation address.
`Readers using this domain will lose access. Remember to also delete the DNS records at your provider.`	Review the consequence and remove the provider's DNS records when you disconnect the domain.
`Domain removed`	The domain has been removed; reconnect it from the connect surface with Connect domain if needed.
`Retry failed`	Review the displayed status and DNS records before trying Retry again.
`Remove failed`	Review the displayed domain state before trying Remove domain again.

Result: You have a message-specific correction to make before repeating the affected action.

Know what happens next

After a successful DNS check, the domain can continue from Waiting for DNS through Verifying and Issuing certificate to Live. A live domain shows Your docs are live at and an Open link. If DNS changes after the domain is live, the status can become Offline; restore the records and select Recover.

When you no longer want to serve documentation from the custom domain, select Remove domain. Review the confirmation text before choosing Yes, remove it or Keep domain. Removing the domain leaves the project's subdomain working. To configure or reconnect an address, continue with Manage custom domains. To return to the wider settings area, use System Settings overview.

Result: The domain is either progressing toward Live, available at its published address, recoverable through Recover, or ready to be reconnected after Removed.

Understand the custom-domain lifecycle

Before you start

Open the domain status

Read the status surface

Check DNS and respond to the status

Handle each domain-status branch

When a check or removal goes wrong

Know what happens next

Was this page helpful?