Manage custom domains

Manage a project's published domain

A subdomain gives your documentation an address on Atloria's documentation domain; your docs are always reachable on an Atloria subdomain. A custom domain serves the same documentation from a domain you control, such as docs.yourcompany.com. The address moves through DNS and certificate checks before it becomes live.

Serve your docs from your own domain, like docs.yourcompany.com.

Before you start

Before changing a published address, select the project whose documentation you want to publish. Have access to the DNS provider for the custom domain and decide whether you are changing the Atloria-hosted subdomain or connecting a separate domain.

Prerequisites

• Know which project you are changing.
• If you are connecting a custom domain, have access to its DNS settings.
• If a custom domain already exists, be ready to check its records and status in the management panel.

The current address is shown as text when one exists. The subdomain card also provides the option to set an address when none exists.

Open the domain settings

The Domain surface is the place where you manage the project's published subdomain and custom domain. It is a tab in the Branding settings page, not the public address itself.

Steps

1. In Settings, select Branding for the project.
2. Select Domain.

Result: The Subdomain and Custom domain cards are available.

Understand the domain settings

The Subdomain card controls the Atloria-hosted address. The Custom domain card connects a domain you control and, after connection, provides the DNS records and status actions for that domain.

The custom-domain area changes with the account state. While settings load, a loading area appears. If loading fails, the page shows Could not load your domain settings. and Try again. When no domain is configured, the connection form appears. When a domain exists, the management panel shows its domain, DNS records, checks, and removal area.

The DNS table uses the headers Type, Name, Value, and Status. Each DNS value has a Copy control. A registrar link appears when the DNS check identifies one and supplies a settings address.

When a control is working, its label changes to Connecting…, Saving…, Checking…, or Removing… while the request is in progress. A successful copy shows Copied!.

Set or rename the subdomain

Use this procedure when you want documentation to use an Atloria-hosted address. The value is checked before it can be saved, so a value that is invalid, unchanged, taken, or reserved does not complete the change.

Prerequisites

• Open the Domain surface.
• Have the subdomain value you want to use.

Steps

1. In Rename subdomain, enter a value containing lowercase letters, numbers, and dashes.

2. Check the message below Rename subdomain.

3. Choose the next action for the message shown below Rename subdomain.

   Message	Next action
   Checking availability…	Wait for the availability result.
   Available	Select Save subdomain.
   Already taken — choose another	Enter a different value in Rename subdomain.
   Reserved — choose another	Enter a different value in Rename subdomain.
   Enter a valid subdomain	Correct the value in Rename subdomain.
   This is your current subdomain	Enter a changed value in Rename subdomain or keep the current address.

When a changed value is valid, the page also shows Docs will be served at followed by the proposed address. After a successful save, the page shows Subdomain updated. If the save fails, it shows Rename failed followed by the returned reason.

If no subdomain exists, the card shows No subdomain yet — publish the project to claim one, or set it here.

Result: The page shows Subdomain updated and the saved address in Current address, or it leaves you at Rename subdomain with the message that explains what to correct.

Connect a custom domain

Use this procedure to serve the documentation from a domain you control. The domain must pass the page's format check before Atloria can start the connection.

Prerequisites

• Open the Domain surface.
• Have access to the domain's DNS provider.
• Use a full domain such as docs.yourcompany.com.

Steps

1. In Custom domain, enter the domain you want to connect.

2. Select Connect domain.

3. Choose the next action for the message shown below Custom domain.

   Message	Next action
   Enter a valid domain, like docs.yourcompany.com	Correct the value in Custom domain, then return to step 2.
   Apex domains need ALIAS-capable DNS — we recommend a subdomain like docs.yourcompany.com	Select use anyway, then return to step 2.

The page may show Could not connect domain followed by the returned reason when the connection is refused. After a connection starts, use the DNS records shown in the management panel at your DNS provider.

Result: The custom domain appears in its management panel with the DNS records to add and check.

Check DNS and handle domain status

The management panel is where you compare the records at your DNS provider with the records required for the connected domain. The page checks automatically every few seconds while the domain is present, and Check now starts an immediate check.

The panel shows Last checked with either the check time or never. Each record can show Observed: followed by the returned value, or nothing yet when no value has been found. A DNS check can also show Your DNS looks managed by followed by the registrar name and Open DNS settings.

Steps

1. Read the Type, Name, and Value columns for each required DNS record.

2. Add the displayed records at your DNS provider.

3. Select Check now to request an immediate check.

4. If a record has a copy control, select Copy for the value you need to add.

5. If the check identifies a registrar and shows Open DNS settings, select it to open the returned DNS settings page.

6. Choose the recovery action shown for the domain.

   Message	Next action
   Retry appears after a verification or certificate failure	Select Retry.
   Recover appears after the domain becomes unavailable	Select Recover.

7. If the panel shows Your docs are live at, select Open to open the published documentation address.

Result: The panel shows the latest DNS check, the returned record observations, and the action that applies to the domain's current condition. When the domain is live, it shows Your docs are live at and Open.

Remove a custom domain

Removing a custom domain disconnects that address and deletes its certificate. The subdomain continues working, but readers using the removed domain lose access. The removal area states Disconnects the domain and deletes its certificate. Your subdomain keeps working.

Caution: Readers using a removed domain lose access. Delete that domain's DNS records at your provider after the removal.

Prerequisites

• Open the Domain surface with a custom domain configured.
• Confirm that disconnecting the domain is the intended correction rather than checking or recovering its DNS configuration.

Steps

1. Select Remove domain.

2. Read the confirmation dialog titled Remove this domain?.

3. Choose whether to keep or remove the domain.

   If you want to…	Next action
   Keep the domain	Select Keep domain.
   Remove the domain	Select Yes, remove it.

4. Delete the domain's DNS records at your provider after confirming the removal.

The confirmation dialog says Readers using this domain will lose access. Remember to also delete the DNS records at your provider. After removal, the page shows Domain removed. If removal fails, it shows Remove failed followed by the returned reason.

Result: The custom domain is removed and the connection form is available again; the subdomain remains the address that continues working.

Know what happens next

After saving a subdomain, use the address shown in Current address. After connecting a custom domain, add the records shown in DNS records and check them until the page shows the live result. If Retry or Recover appears, use that action and then check the records again. The full sequence of domain states and outcomes is described in Custom domain lifecycle.

Result: You have either a saved subdomain, a custom domain progressing through its checks, a live published address, or a connection form ready for the next domain.

When a domain action does not complete

The page also uses Checking availability…, Available, Subdomain updated, Rename failed, Checking…, Last checked, never, Your DNS looks managed by, Observed:, nothing yet, Your docs are live at, and Domain removed while these actions are in progress or complete.