Importing existing documentation

Bring documentation that already exists somewhere else into Meldoc, as local files you can review before anything reaches the server.

What it does, and what it deliberately does not

meldoc import reads an export and writes .meldoc.md files into a directory of your choosing. It does not publish. Nothing is created on the server until you read the diff and run Command Reference yourself.

That separation is the point. An import that writes straight into a workspace leaves you deleting pages by hand when the conversion turns out wrong; an import that writes files leaves you with git diff.

Do not confuse this with Command Reference, which is about aliases of documents you already have here.

Sources

Source	Pass	What it reads
markdown	a directory	Any folder of Markdown: a docs-as-code repository, a tree of README.md, an Obsidian vault
notion	a .zip or an unpacked directory	An official Notion export in Markdown & CSV format

For Notion, export from Settings → General → Export all workspace content, pick Markdown & CSV, and point the command at the archive Notion emails you. The export is used rather than Notion’s API on purpose: the API requires you to share an integration with every page one at a time.

Usage

# See what would happen, write nothing
meldoc import --from markdown ./my-docs --dry-run

# Import a folder of markdown
meldoc import --from markdown ./my-docs --out ./docs

# Import a Notion export
meldoc import --from notion ./Export-abc123.zip --out ./docs

Flag	Type	Default	Description
--from	string	—	markdown or notion
--out	string	docs	Directory to write the imported tree into
--dry-run	bool	false	Print the plan; write nothing
--force	bool	false	Overwrite existing files
--debug	bool	false	Enable debug logging

Exit codes: 0=imported, 1=refused or failed.

What you get

Documents land in the same layout Command Reference produces, so an imported tree and a pulled one are indistinguishable: a document with children owns a directory and lives in its index.meldoc.md, a leaf is a file beside its siblings. Frontmatter carries alias, title and parentAlias.

Links between documents become [[alias]]. Referenced images and files are copied into assets/ and their references repointed, ready for Working with Assets to upload.

Titles that are not Latin are transliterated. A Cyrillic title becomes a readable ASCII alias — Обзор архитектуры gives obzor-arhitektury — because the server’s alias rule is ASCII-only.

Two documents never land on one file. Titles are not unique and paths are derived from them, so a document titled “Index” inside a folder that already owns its index.meldoc.md would collide. The second one takes a -2 suffix instead of overwriting the first, and the report names both source files.

The migration report

Every run writes MIGRATION_REPORT.md next to the imported tree. It lists what the target syntax could not express, each entry keeping the source file it came from:

## callout (1)

- `guide/setup.md` — [!note] became a blockquote

Read it before pushing. It is the only place the import tells you what it could not carry — Obsidian callouts and embeds, Notion databases whose views and rollups have no equivalent, references to files that were not in the export.

After importing

meldoc validate     # catches missing titles and broken links
git diff            # read what the import actually produced
meldoc push         # publish, once you are happy