Importing Markdown documentation

Import existing guides from Markdown without copying each page into the editor. You can select several .md files or a ZIP archive, review the title and address of each article, then save them as drafts for editing and publication.

Before you begin

Open Site → Docs → Upload docs. You need permission to create documentation; publishing also requires the appropriate access. If the upload action is unavailable, see Why can’t I see or edit a feature?.

Keep the original files until you have checked the imported articles. For a large collection, start with a few representative guides: one with headings and lists, one with images or downloads, and one with links to another guide.

Upload creates new articles. It does not update an existing article with the same address. To revise a guide already in Cedros, open that article in the Docs list and edit it. Do not change the import address merely to get around a conflict unless you actually want a separate article.

Prepare your files

Use plain-text Markdown files with the .md extension, saved as UTF-8. Each Markdown file must be 2 MB or smaller. Renaming a Word document or PDF to .md does not convert it; export or convert the text to Markdown first, then review the result.

For multiple articles, either select several files at once or put them in a .zip archive. A ZIP can contain folders, but folder names do not automatically become article addresses or sidebar sections. Give each article an explicit slug when its address matters.

For reliable imports:

• Include useful body text. A file containing only metadata or a title is not enough.
• Use ## for main sections and ### for subsections. Keep the page title in the front matter so it is not repeated in the body.
• Use normal Markdown paragraphs, lists, links, images, tables, and fenced code blocks. Review anything exported as raw HTML, custom components, or template syntax; uploading a file does not install those components.
• Give each article a unique address. Two files called overview.md in different folders can still resolve to the same route.
• Keep images, PDFs, and other attachments out of the docs ZIP. They are not imported into the media library by this workflow.

ZIP archives must be no larger than 100 MB, with at most 1,000 archive entries and 250 MB of uncompressed content. The 2 MB limit still applies to each Markdown file inside. Smaller batches are easier to review and recover if some files need correction.

Add optional front matter

Front matter is a short metadata block at the very beginning of the file, between two lines containing ---. It lets you choose the title, address, summary, product, and section before importing.

Here is a complete example. Replace the sample product and section with the names used by your own documentation:

---
title: "Contact support"
slug: docs/help/contact-support
excerpt: "Send a useful report."
productSlug: help-center
productLabel: Help Center
sectionKey: support
sectionLabel: Support
---

Help your support team
understand the problem.

## Describe what happened

1. Describe your task.
2. Explain what went wrong.
3. Include the error message.

Remove private information
from screenshots before sharing.

Save the file itself without the outer code fence shown above. The first line of the file should be ---, and the body should begin after the closing --- line.

Fields the docs uploader uses

Use one simple value per line. Quote text containing punctuation such as a colon followed by a space. Avoid duplicate keys, nested objects, or multiline YAML values for these fields.

All of these fields are optional, but explicit titles and slugs make a batch easier to check. Without a slug, the uploader derives an address from the first heading or filename; setting only title does not guarantee the same words will be used for the address. Slugs are normalized to lowercase paths with dashes, so always check the resulting Route in the review table.

Without a summary, Cedros takes a short excerpt from the beginning of the body. A matching title heading at the start of the body is removed during import. A different heading remains, so check for duplicate or unintended titles in the editor.

Without section fields, articles start in Getting Started. Reuse the same product and section identifiers as the existing articles they belong with.

Settings to finish after import

The docs uploader does not apply every possible front-matter field. In particular, do not rely on file fields for categories, tags, article order, navigation labels, parents, aliases, visibility, publication status, or scheduled publication.

Set Category and Tags in the article’s Taxonomy tab after import. Category is separate from the sidebar section. For ordering, nesting, aliases, and other navigation changes, use Organizing your documentation navigation.

The upload page also offers Markdown format → Copy example and Copy formatting instructions. The latter gives you instructions you can use with a writing assistant; it does not create or import an article by itself. Review any generated text and metadata before using it.

Check images, downloads, and links

Markdown stores references to images and files; it does not bring those files into Cedros with the article.

1. Upload needed assets to Site → Media, or use an existing approved URL that your readers can access.
2. Replace local references such as images/setup.png or ../files/checklist.pdf with the intended media or download URL.
3. Replace links to source files such as other-guide.md with the other article’s final public route.
4. Check section links after import, especially if you renamed headings.
5. Test every image and download as a visitor before publishing the collection.

A ZIP folder layout does not rewrite relative links or upload attachments. A link that works on your computer or in the old documentation site may fail on the new article. See Uploading and organizing media for asset preparation and delivery URLs.

Review the files before importing

1. Open Site → Docs → Upload docs and choose Choose files, or drop the files onto the upload area.
2. Wait for the review table. Selecting files prepares the review; it does not yet create articles.
3. Check Title, Route, File, and Status for every row. Inferred means a title or slug was not explicitly supplied in the front matter; it is a reminder to verify the result, not an error.
4. Read each Can’t import message. Correct unsupported files, invalid front matter, missing body text, or duplicate addresses before including them in the run.
5. Use Add more files to extend the selection. To replace the selection after editing your local files, use Start over and choose the corrected files again.
6. Open Import options and keep Save as drafts selected for a collection you still need to check. Confirm the number on Import … drafts, then start the import.

The review table is a summary, not an article editor. Fix a wrong title or route in the local file and select it again, or make appropriate edits in the saved draft afterward.

If some rows are blocked, you can import the ready rows and correct the others separately. An existing live or draft entry can already own an address. If two selected files claim the same address, the later conflicting file is blocked. Address checks may be incomplete for a large library, or an address may become unavailable after review, so also inspect the final results.

Publishing directly from the upload page

Import options → Publish immediately changes the action to Import and publish …. Each successfully published article can go live as the batch runs; publication is not held until the entire batch succeeds.

Use this only when the content, links, addresses, and default settings are already ready for readers. For a first import or a collection needing category and navigation work, Save as drafts gives you time to review each article before release. A status field in the file does not replace this choice.

Check Import options again for each run, including after Start over or Upload more; those actions do not necessarily change the selected publication mode.

Finish the import and review the drafts

Keep the upload page open while the run is in progress. Each row reports its own outcome:

• Imported: the article was saved as a draft. If a publishing error is shown beside it, the draft still exists.
• Published: the article was saved and published.
• Failed: the save did not complete successfully; read the row’s error before retrying.
• Can’t import: the file was blocked before saving.

Stop asks the importer to stop before the next file. The current file may finish, and articles already imported or published remain in place. Stopping or starting over is not an undo action.

When one article has been saved, use Open in editor. For several articles, use Review docs to return to the library and open them individually.

Before publishing each draft:

1. Check the title, address, summary, body, and heading hierarchy. Remove leftover export instructions, navigation menus, or repeated title text.
2. Review code blocks, tables, numbered steps, images, and links in the rendered preview, including at a phone-sized width.
3. Set the category and tags, and confirm the product, section, sidebar order, and visibility.
4. Save the reviewed changes, preview the current version, and publish when ready. Follow Creating a documentation article for the editor workflow.
5. Open the public route as a reader. Check the docs index, sidebar, search, related-guide links, and any download or image URLs.

Publish linked guides in a coordinated order so readers are not sent to drafts. Keep an inventory of old and new addresses if this is a migration, and test any aliases or redirects before retiring the old documentation.

Troubleshooting

A file is rejected

Check the .md extension, the 2 MB file limit, and whether the file contains body text beyond its title and metadata. Front matter must start at the top of the file and have both --- delimiters. Invalid YAML can block the file; use the simple example above and check quotation marks and duplicate fields.

For a ZIP error, extract the files locally and try a small selection of .md files. Remove unrelated attachments, reduce the archive size or entry count, and recreate a standard ZIP. Archives with unsupported paths or ZIP64 entries can be rejected.

The title, address, or summary is unexpected

Add explicit title, slug, and excerpt values, then review the file again. ZIP folder names are not an address plan. An omitted slug may come from a section heading rather than the title you intended. Metadata that appears in the article body usually means the front-matter delimiters were not recognized.

The route is already taken

Search the Docs list for the existing article and check its address, including drafts. Edit that article if you are updating it. For a genuinely new guide, choose a distinct slug and reselect the corrected file. Do not delete the existing article simply to clear the conflict.

Only part of the batch imported

Use the row results to separate saved articles from failures. Retry … files returns failed rows to the review step; it does not recreate successful rows. Check the options, then run the import again. Correct blocked files locally and select only the remaining files in a new batch.

If the browser closed, the connection dropped, or the result is uncertain, check the Docs library before retrying. A saved article can exist even if you did not receive its final confirmation. Re-uploading every original file is not a reliable recovery method.

Import succeeded, but publishing failed

Open the saved draft and read the publishing error. Check access, review the current version, and complete publication from the editor after resolving the issue. Do not upload the file again: the draft already exists, and another upload may conflict with its address.

The article is in the wrong section or has broken media

Check product and section fields separately from Category. Finish navigation settings after import. For broken media, replace local file paths with visitor-accessible URLs; importing the Markdown did not transfer the referenced files.

If you need help, provide the filename, intended route, row status, exact error, and whether an article was saved. Remove confidential content before sharing a sample file. See Getting help and reporting a problem.

Related guides

• Creating a documentation article
• Organizing your documentation navigation
• Uploading and organizing media
• Understanding drafts, previews, and publishing
• Changing a page address without breaking links