Source: https://docs.pageloop.ai/guides/import-existing-content

# Import existing content into the Knowledge Base

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

> [!NOTE]
>
> 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**

1. Open **Settings → Knowledge base** and find **Import from Intercom** under **Content**.
2. Click **Import from Intercom**. If the dialog offers more than one connected help center, choose **Intercom**.
3. Read the confirmation and click **Start import**.
4. Watch the import progress. When the import finishes, check the results for failed articles and click **Review PR**.
5. [Review the import pull request](#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**

1. In **Settings → Knowledge base**, connect GitHub if needed and select the GitBook repository.
2. Check the branch being inspected. If your Git Sync content lives on another branch, select that branch so Pageloop checks the intended content.
3. When Pageloop detects the GitBook site, enter **Site name** and **Slug**. Enter **Base path** only if the docs are served under a path prefix.
4. 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.
5. Click **Migrate & connect** and wait for the migration to finish.
6. Click **Review PR**, [review the converted content](#review-the-import-pull-request), 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](#add-api-reference-pages) 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**

1. In **Settings → Knowledge base**, connect GitHub if needed and select the Fern repository.
2. Check the inspected branch and change it if the docs live elsewhere.
3. When Pageloop detects the Fern docs site, enter **Site name** and **Slug**.
4. 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.
5. Confirm the branch shown for the migration, then click **Migrate & connect**.
6. Wait for the migration to finish. Click **Review PR**, [review the conversion](#review-the-import-pull-request), 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.

1. Confirm the destination repository and base branch.
2. Review the added or converted pages, assets, and `docs.json` navigation. Check that expected pages are present and that unrelated content is not being replaced.
3. 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.
4. 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.
5. 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.

![Import from Intercom and the three API Reference spec source options in Knowledge base settings](/images/uploads/screenshot-32e76cc3.png)

### Use a repo file

1. Commit the OpenAPI 3.x JSON spec to the site's tracked branch.
2. Select **Use a repo file** in **API Reference**.
3. Enter its repository-relative path in **Spec path**. Include the directory if the spec is not at the repository root.
4. Click **Use this file**.

Convert a YAML spec to JSON before using this option.

### Upload a file

1. Select **Upload a file**.
2. Click **Choose file** and select an OpenAPI 3.x `.json` file no larger than 2 MB.
3. 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

1. Select **Fetch from URL**.
2. Enter the HTTPS address in **Spec URL**.
3. 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.

> [!WARNING]
>
> 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

1. In **API Reference**, check the displayed spec path to identify the source file.
2. 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.
3. Review and merge the repository change into the site's tracked branch.
4. 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.

## Related pages

- [The Pageloop sidebar](/guides/pageloop-sidebar)
- [Writing docs](/guides/writing-docs)
