Import Existing Documentation

You already have documentation somewhere: a static docs site, a GitHub wiki, a wordpress.org readme or a course in your community. Copying it by hand takes days, and every image and link between pages breaks along the way.

Core Support imports it with one WP-CLI command. Pages land as drafts in a collection, as native blocks. Images are copied into the media library, links between pages point at the new docs and old addresses are recorded for redirects.

Before You Import

• Imports run from WP-CLI only. There’s no import screen in wp-admin.
• Create the collection first under Core Support → Collections, or with wp term create csp_collection "My Product" --slug=my-product.
• Run every import with --dry-run first. It lists each page’s section, slug, title and source address, then saves nothing.

Pick a Source

Source	Type	Sections come from	Order comes from
A docs site, from its sitemap	sitemap	Folders under --prefix	The site’s own navigation
Individual web pages	web	Folders under --prefix	The site’s own navigation
Markdown files or a GitHub wiki	markdown	None, or --section	_Sidebar.md, then file name
A wordpress.org readme	wporg	None, or --section	Overview, Installation, FAQ
A FluentCommunity course	fluentcommunity	The course’s sections	The course’s own order

A Docs Site from Its Sitemap

wp core-support docs import sitemap https://example.com/sitemap.xml --prefix=https://example.com/docs/ --collection=my-product --dry-run

• A sitemap index works too. Core Support follows it to the sitemaps it lists.
• Only pages under --prefix are imported.
• The first folder under the prefix becomes a section. A page at that folder’s own address becomes the section doc, otherwise Core Support creates a short section doc named after the folder.
• A page’s meta description becomes its excerpt.
• The title is the page’s first H1, or the part of its <title> before a separator such as |.

Core Support looks for the article in the usual places, such as article.docs-article, [data-pagefind-body], .docs-content, main article, article, .markdown-body, .entry-content and main. If it picks the wrong element, pass --selector.

Individual Web Pages

wp core-support docs import web https://example.com/guide/ https://example.com/faq/ --collection=my-product --section="Guides"

Markdown Files or a GitHub Wiki

Clone the wiki first, then point the import at the folder:

git clone https://github.com/owner/my-product.wiki.git
wp core-support docs import markdown ./my-product.wiki --source-base=https://github.com/owner/my-product/wiki --collection=my-product

• The title comes from front matter title:, then the first # heading, then the file name.
• A wiki’s _Sidebar.md sets the order. Files it doesn’t list follow in file-name order.
• Home.md becomes an Overview doc and comes first.
• Files whose names start with _, such as _Sidebar.md and _Footer.md, aren’t imported as docs.
• [[Page]] wiki links become links to --source-base plus the page name.
• A folder import reads the .md files directly inside it, not those in subfolders.

Always pass --source-base, even for local files. Without it, the importer has no address to remember each page by. Links aren’t rewritten, no redirects are recorded and a second run adds every page again.

A wordpress.org Readme

wp core-support docs import wporg my-plugin --collection=my-product --section="Getting started"

The readme becomes up to 3 docs: Overview, Installation and FAQ. Empty sections are skipped. Each FAQ question becomes a Details block, and the plugin’s short description becomes the Overview’s excerpt.

The readme’s changelog isn’t imported here. A changelog has its own home, covered in Publish Changelogs by Hand or from a Repository.

A FluentCommunity Course

wp core-support docs import fluentcommunity my-product-training --collection=my-product --publish --no-images --retire

• The course must be on this site. Pass its slug or ID.
• Each published section becomes a section, with its title, and each published lesson becomes a doc in course order.
• Links between lessons, including links into courses imported earlier, point at the new docs.
• --no-images suits a course, because its images are already in this site’s media library.

Import Options

• --collection=<slug>: the collection to import into. Required.
• --prefix=<url>: sitemap and web only. Imports only pages under this address, and folders below it become sections.
• --selector=<selector>: sitemap and web only. The element that holds the article, such as article.docs-article, main or .content.
• --source-base=<url>: markdown only. The address the files were published at.
• --section=<title>: puts every imported page under this section.
• --publish: publishes instead of saving drafts.
• --no-images: leaves image addresses as they are instead of copying the images.
• --retire: fluentcommunity only. Hides the course and redirects its addresses.
• --dry-run: lists what would be imported and saves nothing.

A selector must be simple: a tag, a .class, an #id, an [attribute] or a mix such as article.docs-article, with spaces for nesting (main article).

What the Importer Converts

• Headings, paragraphs, lists, code, quotes, details, separators and images become native blocks.
• Tables and embeds become Custom HTML blocks, which render the same and never fail block validation.
• Quotes that start with a GitHub alert such as [!NOTE], or with a word and a colon such as Tip:, become callouts. Note, Info and Important become Note, Tip becomes Tip and Warning, Caution and Danger become Warning.
• Scripts, styles, forms, buttons, navigation and footers are dropped.
• The page’s first H1 becomes the doc title and leaves the body.

Images are copied into the media library once each, under names such as my-product-install-1.png. JPG, PNG, GIF, WebP and AVIF images are copied, and SVG when your site accepts SVG uploads. An image that can’t be copied keeps its original address, and the import prints a warning.

Run an Import Again

Running the same import again is safe:

• Pages that are new at the source are created.
• Pages that haven’t changed are left alone.
• Drafts nobody has edited are refreshed from the source.
• Docs edited or published since the last import are kept, with a warning such as Kept "Install the plugin" (edited or published since the last import).

Each run ends with a summary of docs created, updated, unchanged and kept, and images copied.

I’d re-run an import freely while the drafts are under review. Once you edit or publish a doc, the importer stops touching it, so later fixes to that doc happen in the editor.

Redirects from Old Addresses

Each imported doc lists its source address under Old addresses in its Doc details box.

• An old address on this site redirects to the doc once the doc is published, as long as nothing else answers there.
• An old address on another domain is recorded, but the redirect needs a rule on that site or its CDN.
• A wordpress.org readme stays where it is. Link to the new docs from it.

Retire a FluentCommunity Course

A course lesson still answers at its old address after the import, so a normal redirect never fires. --retire handles that:

• It sets the course to draft in the community.
• Lesson addresses, with or without /view, redirect to the matching docs.
• The course address, and any lesson with no matching doc, redirects to the collection.

Only published docs take part, so retire a course together with --publish or after you publish its docs. Before that, every lesson address lands on the collection page.

To undo it, set the course back to published in FluentCommunity and remove the course’s entry from the core_support_doc_retired option.

When an Import Goes Wrong

• “Nothing to import. Check the source and –prefix.”: the source had no pages, or none under the prefix.
• “No collection with that slug.”: create the collection first, then use its slug.
• The wrong part of the page came through: pass --selector with the element that holds the article.
• “Could not fetch…” or “…returned HTTP 403.”: the page must answer a plain request with HTTP 200. Core Support follows up to 3 redirects and waits 20 seconds.
• “FluentCommunity is not installed on this site.” or “No FluentCommunity course with that slug or ID.”: check the plugin and the course slug.
• “wordpress.org has no plugin with the slug…”: use the slug from the plugin’s wordpress.org address.

Once the drafts look right, review each one, set its Last reviewed date and publish. Write Product Docs with Collections covers the Doc details box and the reading experience.