Import Markdown Data

The import feature is designed as a starting point to move projects with many Markdown docs to ReadMe. This will be handy if you are just getting started and want to port your old documentation quickly. After you import, the documentation will likely need to be edited to ensure the resulting docs look as desired.

Go to Project Dashboard > Configuration > Project Settings, then scroll down to Project Management.

πŸ“˜

Import File Type

Only markdown (.md) files can be imported into ReadMe. Other file formats (.html, .csv, .doc) are not supported. ReadMe has its own flavor of Markdown, but supports Github-flavored Markdown for most fields.

🚧

Avoid Importing Versions That Already Exist in ReadMe

It's important to note that if there are clashing versions between those existing in ReadMe and the versions you want to import, the versions that you want to import will be bumped up (minor bump), so they don't clash.

For example, if you're trying to import v1.0 docs, but there already exists v1.0 docs in your docs project, your project automatically creates a new version, v1.1, and imports your docs under that new version.

Expected File Format

ReadMe expects the following 5-line header in each Markdown file:

---
title: "your title"
excerpt: "brief description of page contents that show up on previews"
---

To avoid post-import cleanup in the online editor, it's a good idea to add the preceding header. If you don't include this header, then ReadMe bases the page's title on the MarkDown file name.

πŸ“˜

Avoid duplicate file names.

You can't publish Markdown files in a single version that have the same file name. Duplicate file names won't break the import, but you won't be able to publish any duplicated topics until you change their slugs in your project's dash. To avoid this clean-up work, make sure all your file names are unique.

Expected Directory Structure

Import works by taking in a zip file that represents your documentation. ReadMe supports the following hierarchy depth: Category > page > subpage. This means you can have pages with subpages, but those subpages can't have further subpages.

To create a category, create a directory, and populate it with pages.

To create a subpage, create a folder with the parent page name, and create a sibling file with the same name, that contains the Markdown content that you want to appear on the parent page.

The names of the directories and files are turned into the slugs and category names.

For example, if you had a zipped directory containing the following:

v2.0
β”œβ”€β”€ Getting Started.md
β”œβ”€β”€ Getting Started
β”‚   β”œβ”€β”€ Introduction.md
β”‚   β”œβ”€β”€ Best Practices.md
|   └── Features.md
|       Features
|       └──  Open Source.md 
β”‚   β”œβ”€β”€ Hub 2 Upgrade FAQ.md
β”‚   β”œβ”€β”€ Contact Support.md
└── General
    β”œβ”€β”€ Dashboard.md    
    └── Dashboard
        └── Profile.md

This becomes:

Imported TOC.Imported TOC.

Imported TOC.

Importing Example Docs

To see how the import process works, you can use example zipped files for single version and multi version doc projects:

  1. Download one of the two zipped file examples from GitHub.
  2. Import one of the zipped files to your ReadMe project using the button under "General Settings" on your project's dash.
  3. In your project's dash, switch to the version(s) under which the docs were imported. Note that if your project already has a v1.0, then your imported docs appear under v1.1 (or v1.2 if you already have a v1.1)
  4. Drag and drop your imported topics into your desired order (by default, they appear alphabetically in the table of contents).
  5. Publish each topic that you've imported. (Imported topics are only visible to administrators by default).

Single version

This is the structure if you want to import a single version into your project:

Multiple versions

This is the structure if you want to import multiple versions: (The only difference in structure is that there is a directory that sits on top of the versions directory for importing multiple versions)

❗️

Ignored files

File names that start with . or _ will not be imported.

Exporting from ReadMe and Re-importing

Disclaimer: Exporting and importing from ReadMe will get you varied results, as some information is lost within the exporting process. Things such as the order of the categories, pages will be lost within the export process. In addition reference documentation will be imported as regular documentation.

Importing pages with JSON blocks

The importer will attempt to parse pages with block tags as JSON. If there is a failure to parse any of the JSON blobs, the importer will exit with an error.


Did this page help you?