Knowledge Base
Import existing content into the Knowledge Base
Bring existing docs into Pageloop and generate API reference pages from an OpenAPI spec.
Import existing content into the Knowledge Base
Bring your existing articles into a repo-backed Pageloop Knowledge Base, then review the imported content before publishing it. You can also generate API reference pages from an OpenAPI spec.
You must be an Admin to use Settings → Knowledge base. These instructions apply to workspaces where that section is available and to documentation stored in GitHub, not to editing articles in a connected help center.
Import docs
Before you start, install the Pageloop GitHub App and grant it access to the repository you will use for your docs. Know which branch contains the content you intend to import. Open Settings from the Account menu, then select Knowledge base.
Intercom imports articles into an existing Pageloop docs repository. GitBook and Fern migrations start when you connect the source repository while setting up the Knowledge Base; they are not upload options on an existing site's settings page.
Intercom
Prerequisites
- Connect the Intercom workspace that contains your articles in Integrations.
- Set up a repo-backed Pageloop Knowledge Base as the import destination.
- Publish the Intercom articles you want to bring across. The import includes published articles only.
Import
- Open Settings → Knowledge base and find Import from Intercom under Content.
- Click Import from Intercom. If the dialog offers more than one connected help center, choose Intercom.
- Read the confirmation and click Start import.
- Watch the import progress. When the import finishes, check the results for failed articles and click Review PR.
- Review the import pull request, then merge it in GitHub when it is ready. Nothing goes live until you merge the pull request and the site syncs.
Check afterward: Open Knowledge Base and the published site. Compare article titles, body content, images, internal links, and navigation with the Intercom originals. Check any articles listed as failed before treating the import as complete.
Re-importing creates a fresh branch and pull request. If an import stops, use Resume; if a completed import has failed articles, use Retry failed articles rather than starting the whole import again.
GitBook
Prerequisites
- Have the GitBook content in a GitHub repository through GitBook's Git Sync.
- Know the Git Sync branch. It can differ from the repository's default branch.
- If your docs use a URL prefix such as
/docs, know that base path. - Keep an OpenAPI spec available separately if GitBook stores the API reference outside the repository.
Import
- In Settings → Knowledge base, connect GitHub if needed and select the GitBook repository.
- Check the branch being inspected. If your Git Sync content lives on another branch, select that branch so Pageloop checks the intended content.
- When Pageloop detects the GitBook site, enter Site name and Slug. Enter Base path only if the docs are served under a path prefix.
- Review the page and tab counts, skipped spaces, and warnings. Resolve any blocking items before continuing. Translation spaces and spaces outside the repository can be skipped; check the summary rather than assuming every space is included.
- Click Migrate & connect and wait for the migration to finish.
- Click Review PR, review the converted content, and merge the pull request in GitHub. Pageloop does not merge it for you. The Knowledge Base fills after the merge syncs; you do not need to re-import.
Check afterward: Compare navigation, nested pages, links, images, and any pages called out in the migration report with the GitBook site. If the summary says the OpenAPI spec is outside the repository, add the API reference after migration.
Fern
Prerequisites
- Have a Fern docs site in a GitHub repository, including its docs configuration and referenced pages. An SDK-only repository is not a docs site.
- Know the branch that publishes your docs.
- Make sure referenced API specs and pages are accessible in the repository.
Import
- In Settings → Knowledge base, connect GitHub if needed and select the Fern repository.
- Check the inspected branch and change it if the docs live elsewhere.
- When Pageloop detects the Fern docs site, enter Site name and Slug.
- Review the migration summary and warnings. Resolve blockers before continuing. Pay particular attention to unreadable pages and MDX features that need manual editing. If the inventory is incomplete, check the pages that Pageloop could not inspect.
- Confirm the branch shown for the migration, then click Migrate & connect.
- Wait for the migration to finish. Click Review PR, review the conversion, and merge it in GitHub when ready. Your pages appear after the merge syncs.
Check afterward: Verify the page and tab structure, images, links, and API reference. Open pages with custom components or conversion warnings and check the rendered body, not just the title in the navigation. Use the migration report to track anything that still needs editing.
Review the import pull request
For each source, treat the pull request as a proposed migration, not proof that every page converted correctly.
- Confirm the destination repository and base branch.
- Review the added or converted pages, assets, and
docs.jsonnavigation. Check that expected pages are present and that unrelated content is not being replaced. - Read the import results and warning details. Resolve missing pages, failed assets, broken links, or rendering problems before merging. If the import was interrupted, return to Settings → Knowledge base to resume it.
- Merge the reviewed pull request in GitHub, then return to Settings → Knowledge base and wait for the sync to finish. Use Sync now if you need to retry the sync.
- Open Knowledge Base and View site to check both the imported tree and the published pages. A completed import job does not mean its pull request has merged or its content is live.
If Pageloop could not open the pull request, the import panel names the branch where the content was saved. Open a pull request from that branch in GitHub instead of assuming the imported content was lost.
Review the follow-up docs run
After a GitBook or Fern import merges and syncs, Pageloop starts a follow-up docs run for actionable gaps recorded by the importer. The run proposes fixes for review; it does not publish them automatically. When the import panel shows Open follow-up run, follow that link to review the run in the Inbox. Check the published content yourself as well—the follow-up run does not replace migration review.
Add API reference pages
Use Settings → Knowledge base → Content → API Reference to supply an OpenAPI 3.x spec. The spec used by Pageloop is a JSON file in the docs repository. The supported size is up to 2 MB.
Use a repo file
- Commit the OpenAPI 3.x JSON spec to the site's tracked branch.
- Select Use a repo file in API Reference.
- Enter its repository-relative path in Spec path. Include the directory if the spec is not at the repository root.
- Click Use this file.
Convert a YAML spec to JSON before using this option.
Upload a file
- Select Upload a file.
- Click Choose file and select an OpenAPI 3.x
.jsonfile no larger than 2 MB. - Check the selected filename, then click Add API reference.
Pageloop commits the spec as api-reference/openapi.json beside the site's config file. Convert YAML to JSON before uploading. If that destination already contains a different file, resolve the reported collision before retrying.
Fetch from URL
- Select Fetch from URL.
- Enter the HTTPS address in Spec URL.
- Click Fetch and add and review any error or warning.
This option accepts JSON or YAML; Pageloop converts YAML to JSON and commits the resulting spec at the same destination as an upload.
Fetching from a URL is a one-time import. Pageloop does not follow later changes at that URL. Updating the remote spec alone will not update your API reference.
Review and sync the spec
All three options set the openapi path in the site's docs.json. The path is repository-relative, not relative to the config file. For a versioned site, the setup adds the spec to the default version's entry; other versions retain their own specs.
On an unprotected branch, Pageloop commits the change and starts a sync. On a protected branch, Pageloop opens a pull request instead. Review the spec and config changes, then merge the pull request; the API reference goes live after the merge syncs. If the confirmation says the change was committed but the sync did not start, use Sync now in Knowledge base settings.
The sync reads the spec and generates an endpoint page for each operation, with an API Reference section in the navigation. Check the generated operations, parameters, request bodies, responses, and navigation on the published site. Review sync warnings if expected endpoints are missing.
Update the spec later
- In API Reference, check the displayed spec path to identify the source file.
- Edit or replace that JSON file in the repository. For a URL-imported spec, obtain the updated spec and replace the committed copy; changing the original URL's contents is not enough.
- Review and merge the repository change into the site's tracked branch.
- Wait for the sync, or use Sync now, then verify the regenerated endpoint pages.
Update the spec rather than editing generated endpoint pages. If you move the spec, update its openapi path in docs.json in the same change.

