Source: https://docs.pageloop.ai/guides/knowledge-base-publishing-settings

# Configure Knowledge Base publishing settings

# Configure Knowledge Base publishing settings

Use the **Audience** group in Knowledge base settings to choose where readers reach your documentation, which versions they can read, and whether they must sign in.

> [!NOTE]
>
> You must be an Admin with a Pageloop-hosted docs site. These settings do not configure a help center hosted by an external provider. Login controls are available when your settings show **Require a login**.

## Open the publishing settings

1. Open the **Account** menu in the top bar and select **Settings**.
2. Under **Workspace**, select **Knowledge base**.
3. Scroll to **Audience**. This group contains **Custom domain**, **Versions**, and, when available, **Require a login**.

![Custom domain, Versions, and Require a login under Audience in Knowledge base settings](/images/uploads/screenshot-cc29aeae.png)

## Add a custom domain

You need access to the DNS settings for the domain you want to use.

1. In **Custom domain**, enter your hostname, such as `docs.example.com`. If you already have a custom domain, first select **Add domain** to open another entry form.
2. If **Domain role** appears, choose **Serves your docs** to serve the site at this address. Choose a **Redirects to** option instead when the address should send visitors to an existing custom domain.
3. For a root domain such as `example.com`, review the **Also redirect [www.example.com](http://www.example.com) here** checkbox. Leave it selected if you also want that redirect; the redirect domain needs its own DNS setup.
4. Select **Add domain** to save the hostname.
5. At your domain registrar or DNS provider, add every record displayed by Pageloop. Match the **Type**, **Name**, and **Value** columns; use **Copy** to copy a record's value. Use the records shown for your domain rather than values from another site's setup.
6. Return to Knowledge base settings. While DNS verification is pending, Pageloop checks automatically while the page is visible. Select **Check now** to check without waiting for the next automatic check.
7. Wait for **Live**, then open the domain's link and check that your docs load over HTTPS.

### Check the domain's status

| Status                  | What to do                                                                                                                                     |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pending DNS**         | Confirm that every displayed DNS record is saved at your DNS provider. Allow time for the records to become available, then use **Check now**. |
| **Issuing certificate** | The domain is verified, but HTTPS setup is still finishing. Wait for **Live**; certificate issuance usually takes a minute or two.             |
| **Failed**              | Check the DNS records, then select **Retry**.                                                                                                  |
| **Live**                | Open the domain to verify the reader experience.                                                                                               |

### Remove a custom domain

1. Find the domain in **Custom domain** and select **Remove**.
2. Read the confirmation. Removing a domain that serves your docs also removes the redirect domains that point to it.
3. Select **Yes, remove** when you are ready. Visitors to the removed domain will no longer reach your docs through that domain. Removing a redirect domain stops that redirect.

Your default address, `https://<slug>.docs.pageloop.ai`, stays available when you add or remove a custom domain. Find your exact address under **Site → Slug**. The slug is fixed at site creation. An available address does not mean public access: the site's login requirement still applies.

## Publish more than one version

Use versions when readers need documentation for different product or API releases. You need a connected repository to use **Create version**. A site supports up to five versions.

1. In **Versions**, select **Create version**.
2. Under **What to version**, choose **Help center version** or **API version**. API versions require an OpenAPI reference; **API version** is disabled when no reference is available.
3. Enter **New version name**. Your live docs continue under this name, become the default, and receive the **Latest** tag. Check the **URL base** shown after you enter the name.
4. For the first version you create, fill in **Archive current version as** with a different name for the existing documentation. For an already-versioned site, the dialog identifies the current default that will be archived instead.
5. Select **Create version** and wait for the sync. Creation writes the version configuration and snapshots to your repository. If the published branch is protected, review and merge the resulting pull request before expecting the versions to appear on the site.
6. Check the version list for **Default**, then open your site and test the version switcher and each version's links.

![Create a version dialog with Help center version selected and fields for the new and archived version names](/images/uploads/screenshot-6a61e78e.png)

### URLs and the default version

Each version has its own URL base derived from its name, such as `/v1-0` for `v1.0`. The default version is also served at the site's ordinary URLs without a version prefix. Creating another version makes that new version the default and archives the previous default; existing unprefixed links therefore follow the default rather than pinning readers to the archived version.

For help center versions, the switcher appears throughout the site. When versions differ only in API reference content, the switcher appears on API reference pages; the shared help center pages remain versionless.

### How edits apply

| Version type            | What is archived                                                                       | Effect of later edits                                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Help center version** | A separate copy of the help center pages and, when present, the OpenAPI specification. | Edits to the continuing live pages do not update the archived copies. Edit the intended version's pages when you need to correct that version. |
| **API version**         | A snapshot of the OpenAPI specification. Help center pages stay shared.                | API changes affect the continuing live reference, not the archived specification. Edits to shared help center pages appear across versions.    |

Creating a version snapshots repository content, not unpublished editor drafts. Review and publish any changes you want included before creating the version. Version snapshots are not supported for sites configured with AsyncAPI.

## Control who can read the site

**Audience** is a group of settings, not a public/private dropdown. Use **Require a login** to control reader access.

- With no login requirement, anyone with the link can read the site.
- With a login requirement, your identity provider or login application authenticates readers. **Allowed email domains** can further restrict admission. Access is not granted by inviting readers to your Pageloop workspace.

### Require a login

Before setup, have a working HTTPS docs address and the configuration for your identity provider or login application.

1. Under **Require a login**, select **Set up**.

2. Choose a **Sign-in method** and complete the corresponding fields:

   | Method                    | Configuration                                                                                                                                                                                                                                                  | How readers gain access                                                                               |
   | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
   | **Single sign-on (OIDC)** | Enter **Issuer URL**, **Client ID**, **Client secret**, and **Scopes**. Scopes must include `openid`. Register every displayed **Redirect URLs** entry as an allowed redirect URI on the client in your identity provider.                                     | Your provider signs the reader in, then Pageloop checks admission.                                    |
   | **Signed token handoff**  | Enter **Login URL**, **Public key** in PEM or JWK format, **Token issuer**, and **Algorithm**. Your login application must sign tokens and return readers to the supplied redirect URL, using the displayed **Return URLs** and putting the token after a `#`. | Your login application authenticates the reader and hands back a signed token that Pageloop verifies. |

3. Set **Allowed email domains** to space-separated domains if only those addresses should be admitted. Leaving this field empty admits anyone your provider signs in. Google sign-in requires at least one allowed email domain. For Microsoft OIDC, use your tenant-specific issuer rather than a shared multi-tenant issuer.

4. Select **Require a login** to save and enable the requirement. Resolve any validation or readiness error, then check for **On**. **Saved, not active** means the settings are stored but the site is still public; do not treat that status as protected access.

5. Test a docs link as a signed-out reader and with both an allowed and a disallowed account.

Use **Edit** and **Save changes** to revise the configuration. To make the site public again, select **Turn off** and confirm. Anyone with the link can then read the site.

### What readers see

A signed-out reader is sent to your identity provider for OIDC or to your **Login URL** for signed token handoff. After a successful sign-in and admission check, the reader returns to the requested page. A reader refused admission sees **You don’t have access** rather than the documentation. Sign-in failures show an error page; temporary failures offer **Try again**.

The login requirement covers the whole site, including Markdown versions of pages, `llms.txt`, and search. The default docs address is not a way around the requirement. Preview addresses change each time a preview is created; sign-in on a preview works only if your provider accepts that address too.

## Related

- [The Pageloop sidebar](/guides/pageloop-sidebar) — find Settings and Knowledge Base.
- [Writing docs](/guides/writing-docs) — page files, metadata, and navigation.
