Hupspot knowledge base migration guide

Migrating an existing knowledge base into Hubspot can be done efficiently if you understand how Hubspot articles are structured and how the CSV import process works. This guide walks you through planning, exporting, transforming, and importing your content so your support site is ready to use with minimal cleanup.

How Hubspot knowledge base articles work

Before you move content, it is important to understand the components of a knowledge base article in Hubspot. During migration, each of these elements must be mapped correctly from your source system.

In Hubspot, a standard knowledge base article typically contains:

• Article title
• Article body content
• Category and subcategory assignments
• SEO title and meta description fields
• Article URL slug
• Status (draft or published)

When migrating from another platform, you may not have one‑to‑one matches for every field. In that case, decide which parts are essential and which can be added later within Hubspot after the core import.

Plan your Hubspot migration strategy

A careful plan prevents missing articles, broken structure, and duplicate URLs. Use the following steps to prepare your content before importing into Hubspot.

1. Audit your existing knowledge base

Start by reviewing what you already have. Create a list or spreadsheet with:

• All article titles and IDs from your current tool
• Existing categories and subcategories
• Traffic or usage metrics to prioritize high‑value content
• Articles that are outdated or can be merged

This audit helps you decide which content is worth moving into Hubspot and which can be archived instead of imported.

2. Design your Hubspot category structure

Hubspot uses categories and subcategories to organize your public knowledge base. During migration, a clear structure will improve navigation and search performance.

Define:

• Main categories that match broad product areas or topics
• Subcategories that group specific features or workflows
• Naming conventions for consistency within Hubspot

Update your migration spreadsheet so each article is assigned to a category and, where relevant, a subcategory that reflects your future structure.

Export content for Hubspot import

Once your structure is defined, you need to export data from your current knowledge base so it can be mapped to the fields expected by Hubspot.

3. Export articles to CSV or similar format

Most documentation tools allow you to export articles as CSV, Excel, or a similar table format. When possible, export at least the following fields:

• Title
• Body or HTML content
• Category or folder
• Subcategory (if available)
• Existing URL slug or ID
• Status (published or draft)

If your system does not support CSV export, you may need to use an API or a manual copy‑and‑paste workflow and then organize the data into a spreadsheet that matches Hubspot requirements.

4. Clean and normalize your exported data

Before bringing anything into Hubspot, spend time normalizing the exported spreadsheet. This is a critical step that reduces manual rework later.

Focus on:

• Ensuring every row represents a single article
• Removing duplicate rows or test articles
• Standardizing category and subcategory names
• Checking for broken formatting or unsupported HTML

Make sure all articles use the same encoding and that special characters are rendered correctly so they will display properly in Hubspot after import.

Use the Hubspot knowledge base import template

Hubspot provides a dedicated CSV template that defines the fields you can import into the knowledge base. Using this template is the most reliable way to complete a bulk migration.

5. Download the Hubspot import template

In your Hubspot account, navigate to the knowledge base settings and locate the article import tool. From there, download the official CSV template. This file typically includes columns such as:

• Article Title
• Article Body
• Category
• Subcategory
• Article Slug
• Meta Description
• Article Status

Keep a backup copy of the original template so you can revert if needed during data preparation.

6. Map your existing data to Hubspot fields

Next, copy or map fields from your exported spreadsheet into the Hubspot template. For each article:

1. Paste the title into the Article Title column.
2. Insert the cleaned body content into the Article Body column.
3. Fill in Category and Subcategory according to your new structure.
4. Create or adapt a URL slug that is short, descriptive, and unique.
5. Add a meta description if you want to optimize search results.
6. Select a status (usually draft for the first import into Hubspot).

Avoid leaving required fields blank; incomplete rows may cause errors during the import process.

Import your knowledge base into Hubspot

After you complete the CSV template, you are ready to run a bulk import and create knowledge base articles in Hubspot.

7. Run a test import in Hubspot

Always start with a small batch of articles, for example 5 to 10 rows. In Hubspot:

1. Open the knowledge base import tool.
2. Upload the CSV with your test rows.
3. Confirm field mappings if Hubspot prompts you.
4. Trigger the import and wait for it to finish.

Then review the created articles to verify formatting, images, headings, links, and categories. Fix any issues in the CSV before importing the full set of articles.

8. Import the full set of articles

Once the test looks correct, repeat the same steps with your full CSV file. During this larger import, you may see processing times vary based on the volume of rows. When the import finishes, confirm that:

• Total article count matches your spreadsheet.
• Categories and subcategories appear as expected in Hubspot.
• No articles show as missing or failed in the import summary.

If the tool provides an error log, download it and correct any rows that did not import, then re‑run a smaller import for those specific records.

Post‑migration cleanup in Hubspot

After your main import completes, there are several refinement steps you can perform inside Hubspot to ensure your knowledge base is ready for customers.

9. Review formatting and article design

Open a selection of migrated articles and check:

• Heading hierarchy (H1, H2, H3) is consistent.
• Bullet and numbered lists render correctly.
• Images display properly and have alt text.
• Internal links between articles point to the new Hubspot URLs.

Fix common patterns directly in Hubspot or update your CSV and re‑import if a broad set of articles requires the same adjustments.

10. Optimize categories and navigation in Hubspot

With content in place, refine your navigation so users can find answers quickly. In the knowledge base settings of Hubspot:

• Reorder categories to highlight the most important topics.
• Merge or rename categories that are too similar.
• Confirm that each article appears in the right location.

A clear hierarchy inside Hubspot also supports better on‑site search performance and user satisfaction.

Useful resources for Hubspot migration

For detailed, product‑specific instructions and the latest interface changes, consult the official Hubspot knowledge base migration documentation at this external guide. It explains current limitations, supported fields, and any updates to the CSV template used by Hubspot.

If you need strategic help planning a complex knowledge base move, you can also work with specialists. For example, the team at Consultevo helps organizations design support structures and content operations tailored to their use of Hubspot and other CRM tools.

By planning your structure, cleaning exported data, using the official import template, and validating content after import, you can complete a smooth knowledge base migration into Hubspot while preserving article quality and user experience.

Need Help With Hubspot?

If you want expert help building, automating, or scaling your Hubspot , work with ConsultEvo, a team who has a decade of Hubspot experience.

Scale Hubspot

“`