Skip to content

Migrating from docs-as-code

If you are coming from a docs-as-code setup (Markdown files in a Git repo, built with a static site generator like Docusaurus, MkDocs, or Hugo), this guide is for you. Topicary changes a few assumptions while preserving the parts that matter.

What you are gaining

Visual editing. Technical writers and subject matter experts edit in a WYSIWYG editor instead of raw Markdown. This removes the "learn Git and Markdown" barrier for contributors who are not developers.

Structured reuse. Components (reusable content blocks) replace copy-paste. Edit a component once, and every topic that references it updates automatically. In docs-as-code, reuse means duplicating files or writing custom include plugins.

Multi-channel output. Publish web, PDF, and Markdown from the same source. Docs-as-code tools typically produce one output format. Adding PDF usually means a separate pipeline.

Built-in review. Review sessions with inline comments replace pull request reviews. Reviewers access content through a link, with no Git account needed.

Conditions and variables. Publish different content for different audiences from a single source. In docs-as-code, this typically requires custom frontmatter logic or separate branches.

These gains span different plans. Visual editing and web/PDF/Markdown output are on every plan (including Free). Version history, review sessions, and variables are on the Team plan. Components and conditions are on the Business plan. See Plans and limits for the full breakdown.

Moving to a CCMS is a mental model shift, not just a tool swap. In docs-as-code, content structure lives in the filesystem (folders, filenames, sidebar configs). In Topicary, structure lives in maps, and topics exist independently of any particular hierarchy. A single topic can appear in multiple maps without duplication. This separation is what enables structured reuse.

What changes

Docs-as-code

Topicary

What this means

Markdown files

Topics (rich editor with Markdown import)

Content lives in a structured editor, not flat files

Folders

Maps (define structure and hierarchy)

Structure is decoupled from content: one topic, many maps

Git commits

Auto-versioned snapshots (every save)

No manual commits; every change is tracked automatically

Pull requests

Review sessions (token-based, no Git)

Reviewers need a browser, not a Git account

Build + deploy pipeline

One-click publish

No CI/CD configuration or build scripts

Static site generator config

Publication targets (conditions, variables, format)

Output configuration is per-target, not per-build

includes / custom plugins

Components (first-class reuse)

Single-source reuse without plugin dependencies

Separate branches for each audience

Conditions on content blocks

One source, multiple filtered outputs

The migration path

  1. Import your Markdown files. Drag your .md files, or a .zip of your docs folder, into Topicary. A folder zip preserves your directory hierarchy as a map automatically; when you select several loose files instead, keep the "Create a map from folder structure" checkbox selected.

  2. Review imported topics. Most Markdown transfers cleanly. Check for custom syntax (admonitions, tabs, custom shortcodes) that lack equivalents. Adjust formatting where needed.

  3. Organize your map. The imported folder structure becomes your initial map. Adjust the hierarchy. You are no longer constrained by filesystem conventions. Move topics, adjust nesting, add section headers.

  4. Extract components. Look for content that appears in multiple topics (setup prerequisites, contact blocks, disclaimers). Extract these into components and replace the duplicates with references.

  5. Set up conditions and variables if you serve multiple audiences. This replaces the "maintain separate branches" or "custom frontmatter" approach from docs-as-code.

  6. Publish. Create a publication target and publish. Compare the output against your old site to verify completeness.

Here is what a typical docs-as-code project structure looks like before and after migration:

# Before: docs-as-code (filesystem)
docs/
  getting-started/
    index.md
    installation.md
    quick-start.md
  guides/
    authentication.md
    billing.md
  _includes/
    support-contact.md      # manual include
  sidebars.js               # navigation config
  docusaurus.config.js      # build config
# After: Topicary (structured content)
Topics:
  - Installation
  - Quick start
  - Authentication
  - Billing
Components:
  - Support contact block    # referenced by any topic
Map: "User Guide"
  - Getting started
    - Installation
    - Quick start
  - Guides
    - Authentication
    - Billing
Publication target: "docs.example.com"

The filesystem hierarchy becomes a map. The _includes directory becomes components. Build configuration becomes a publication target.

Keeping a Git connection

This feature requires the Enterprise capability tier (the Business ). During the beta, every project is on the free Solo tier, so this feature is locked by default: go to Settings ▸ Billing and request Enterprise access to unlock it.

On the Business plan, Topicary supports bidirectional GitHub sync. Topic content renders to Markdown and is pushed to a GitHub repository from the editor's sync panel (push on demand, or turn on the auto-sync toggle), and changes made directly in the repository can be pulled back into Topicary. A GitHub webhook on the push event triggers automatic pulls, and edits made on both sides since the last sync surface in a conflict-resolution dialog. This keeps a Git-based copy in step with your docs and supports workflows that depend on a repository (CI checks, automated deployment, changelog generation).

If your team has compliance or audit requirements that mandate a Git history, enable GitHub sync so pushed content gives you a Git-based audit trail alongside Topicary's built-in version history.

Common friction points

Giving up direct file access. In docs-as-code, you edit files with your preferred editor and run git diff to review changes. In Topicary, the editor is the interface. The tradeoff is accessibility: non-technical contributors can participate without learning Git.

Topic granularity. Docs-as-code files can be any length. Topicary topics work best when each covers one concept or procedure. You may need to split long files during migration. This feels like extra work upfront but pays off when you start reusing topics across maps.

Component extraction is iterative. You will not identify every reuse opportunity during migration. Import first, organize second, extract components as you notice repeated content. Trying to plan all components upfront slows the migration without improving the outcome.

Review workflow differences. Pull request reviews happen in Git with diffs and approval flows. Topicary review sessions happen in the browser with inline comments. The feedback loop is similar; the tool is different. Reviewers who are not developers tend to prefer the browser-based approach.

See also

Was this page helpful?