My documentation import failed or is taking too long
Most import problems come from the source: a file the importer can't read, an upload that is too big, or a crawl that takes minutes. Start with the summary the import shows when it ends, then work through the checks below.
#Read the summary first
When an import finishes, the page shows a summary. It tells you:
- Where the articles were read from (an importer's name, or
crawl). - How many articles were found.
- What was written, what was skipped, and what was brought over.
- Whether the knowledge base was indexed afterwards, and what the indexer said if it didn't finish cleanly.
- Anything the importer noticed on the way, under Worth a look.
If articles are missing, the skipped count and Worth a look are the first places to check.
#If the import stalls or stops part way
The progress bar updates as the import runs. A crawl of a public help center can take minutes. Give it time before you assume it is stuck.
If the import ends with "the import stopped part way", it ended without a result. Run it again. If an article was already imported, the second run leaves it alone unless you turn on the option to replace articles already here.
Note
The import form takes either an upload or an address, never both. If you fill in both, the import won't run as you expect.
#If you uploaded a file
You can upload:
- A ZIP of the export. Markdown, HTML, GitBook and Notion exports are all read. A Notion export arrives as a ZIP inside a ZIP, and that's fine.
- A single Markdown or HTML file.
Anything else is refused. If you upload an image or another file type, the error asks for a ZIP of the export.
Check these causes:
| What you see | What it means | What to do |
|---|---|---|
| The file is "not a ZIP" | The upload has a .zip name but isn't a real ZIP | Export again, or re-create the ZIP |
| "more than N files" | The archive holds more files than the importer allows | Split the export into smaller ZIPs |
| A file is "over" the size limit | One file inside the ZIP is too large | Remove or shrink that file |
| "unpacks to more than" | The ZIP is small, but its contents are too big | Split the export into smaller ZIPs |
| "no Markdown or HTML" | The ZIP contains no articles, only images or other files | Check you zipped the right folder |
The upload itself also has a maximum size. The importer also caps the size of each article and each image.
#Why some files don't become articles
- Folders become collections. Files at the top of the export go into a collection named after the folder you zipped.
- A
README.mdis not treated as an article. - Clutter such as
__MACOSXfolders and.DS_Storefiles is left out. - Files with paths that try to leave the archive are ignored.
- Images are brought over when your articles link to them with a relative path, such as
.
#If you entered an address
- An address on
zendesk.com, such ashttps://acme.zendesk.com/hc/en-gb, is read through Zendesk's help center API. No key is needed. The part after/hc/sets the language. - Any other address is crawled. An
http://address is crawled ashttps://. - An address that isn't a web address, such as
ftp://…, is refused with "not a web address".
The address must be a public help center. A crawl can only read pages it can reach without signing in. If the help center is private, export it and upload the file instead.
#If the articles imported but search doesn't find them
After the articles are written, HelpWell indexes the knowledge base. If the indexer reported a problem, the summary says what it said. Fix what it names, then run the import again.
What the import options do
Two options change what the import writes:
- Import every article as a draft. Nothing goes live until you publish it.
- Replace articles already here. Articles already in the knowledge base are overwritten. Leave it off to keep them.
Was this article helpful?
Still stuck?