Skip to content

Migrating from docs-as-code

If you're coming from a docs-as-code setup — Markdown files in a Git repo, built with a static site generator like Docusaurus, MkDocs, or Hugo — Topicary changes a few assumptions while preserving the parts that matter.

What you're 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 aren't 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 via a link — 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.

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 per 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. Check "Create a map from folder structure" to preserve your directory hierarchy as a map.

  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're 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

Topicary supports one-way GitHub sync — pushing published Markdown to a GitHub repository on every publish. This maintains a Git-based backup and enables workflows that depend on a repository (CI checks, automated deployment, changelog generation).

This is a push (Topicary to GitHub), not a bidirectional sync. Topicary is the source of truth; the repository is a downstream output.

If your team has compliance or audit requirements that mandate a Git history, enable GitHub sync. Every publish pushes the current content to a repository, giving 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 won't 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 aren't developers tend to prefer the browser-based approach.

See also

Was this page helpful?