Knowledge Base

Configure Knowledge Base publishing settings

Add a custom domain, publish multiple versions, and control reader access to your hosted documentation.

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.

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.

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

StatusWhat to do
Pending DNSConfirm that every displayed DNS record is saved at your DNS provider. Allow time for the records to become available, then use Check now.
Issuing certificateThe domain is verified, but HTTPS setup is still finishing. Wait for Live; certificate issuance usually takes a minute or two.
FailedCheck the DNS records, then select Retry.
LiveOpen 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.

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 typeWhat is archivedEffect of later edits
Help center versionA 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 versionA 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:

    MethodConfigurationHow 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 handoffEnter 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.