Skip to content

Import from Markdown

Bring existing Markdown content into Topicary as topics. Markdown import is available on every plan, including the Free plan.

Before you begin

  • Files must use standard CommonMark or GFM syntax; custom Markdown extensions (admonitions, tabs, math blocks) are not supported

  • Maximum file size: 5 MB for each file, or 50 MB as a zip archive

Plan your migration

Markdown import is the cleanest migration path: the format translates directly to Topicary's editor with minimal loss.

  1. Organize files first. The folder structure becomes the map hierarchy when you import a folder as a zip. Arrange folders and files in the order you want before importing.

  2. Check image references. When you import a zip that includes the image files (for example a ./images/ folder alongside the Markdown), Topicary uploads them and rewrites the paths automatically. When you import loose .md files without the images, local paths (./images/screenshot.png) are kept as references but the files are not uploaded, so use absolute URLs or re-upload after import.

  3. Use YAML frontmatter for titles. If your Markdown files include title: in YAML frontmatter, Topicary uses that as the topic title. Otherwise it falls back to the first H1 heading, then the filename.

Import files

  1. Go to Topics in the sidebar.

  2. Click Import, or drag Markdown files directly onto the page.

  3. In the import dialog, select .md or .markdown files.

  4. Preview cards appear showing the extracted title, format badge, and a content snippet.

  5. Click Import to create topics.

How titles are extracted

Topicary checks for a title in this order:

  1. YAML frontmatter title field

  2. The first # H1 heading in the content

  3. The filename (without extension)

Here is an example showing how Topicary extracts the title from YAML frontmatter:

---
title: Configure single sign-on
description: This field is ignored during import.
author: Jane Smith
---

# Configure single sign-on

Follow these steps to enable SSO for your organization.

In this example, Topicary uses the frontmatter title value ("Configure single sign-on") as the topic title. The description and author fields are ignored; only title is extracted.

Only the title field from YAML frontmatter is used during import. All other frontmatter fields (description, author, tags, custom metadata) are silently ignored. If you need that metadata in Topicary, apply it manually using tags or custom fields after import.

What is preserved

  • Headings (H1 to H6)

  • Bold, italic, strikethrough, inline code

  • Bullet lists, ordered lists, task lists

  • Tables

  • Code blocks with language hints

  • Blockquotes

  • Images (uploaded from a zip; kept as URLs when you import loose files without the image files)

  • Links

Import multiple files with structure

When you select more than one file at once, the import dialog shows a "Create a map from folder structure" checkbox (selected by default). Leave it checked to preserve the directory hierarchy as a map, where subdirectories become nested sections. A single zip of a docs folder always builds this map automatically, so the checkbox appears only for multi-file selections.

Before importing a folder of Markdown files, arrange the files and subfolders in your desired order. Topicary uses alphabetical ordering from the filesystem, so prefixing filenames with numbers (for example, 01-getting-started.md, 02-configuration.md) gives you control over the initial map order.

What is not preserved

  • Local image files in loose (non-zip) imports: the reference is kept but the file itself is not uploaded, so use absolute URLs or re-upload after import. Zip imports that include the image files upload them automatically.

  • YAML frontmatter fields other than title: custom metadata fields are ignored

  • HTML blocks embedded in Markdown: raw HTML may not render as expected; review after import

  • Custom Markdown extensions (admonitions, callout syntax, math blocks from specific renderers): only standard CommonMark and GFM syntax is supported

Limits

  • Maximum file size: 5 MB for each file

  • Maximum archive size: 50 MB (200 MB decompressed)

Post-import checklist

  1. Review imported topics for formatting accuracy. Most Markdown transfers cleanly.

  2. Re-upload any images that used local file paths and were imported as loose files rather than inside a zip.

  3. If you imported a folder structure as a map, check the hierarchy and adjust ordering.

  4. Identify repeated content across topics and extract it into Topicary components for single-source reuse.

  5. Publish a test target and review the output.

See also

Was this page helpful?