Skip to content

Import from Markdown

Bring existing Markdown content into Topicary as topics. Import is available on Pro, Team, and Business plans.

Before you begin

  • You need a Pro, Team, or Business plan

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

  • Maximum file size: 5 MB per 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 check "Create a map from folder structure." Arrange folders and files in the order you want before importing.

  2. Check image references. Local image paths (./images/screenshot.png) are preserved as URLs but the image files are not uploaded. Use absolute URLs or plan to re-upload images 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's preserved

  • Headings (H1–H6)

  • Bold, italic, strikethrough, inline code

  • Bullet lists, ordered lists, task lists

  • Tables

  • Code blocks with language hints

  • Blockquotes

  • Images (as URLs — local image paths are not uploaded)

  • Links

Import multiple files with structure

When importing multiple files at once, check "Create a map from folder structure" to preserve the directory hierarchy as a map. Subdirectories become nested sections.

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 (e.g., 01-getting-started.md, 02-configuration.md) gives you control over the initial map order.

What's not preserved

  • Local image file paths — the reference is kept but the image file itself is not uploaded; use absolute URLs or re-upload after import

  • 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 per 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.

  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?