Import & Export

Moving content into and out of Chinaski is a set of concrete tools: a Markdown importer for files with front matter, JSON/CSV import and export for structured content, bulk creation, and an async job queue for very large operations. This page walks through each in turn.

Importing Markdown files

If your content already lives as .md files (from another CMS, a static site, or a writing tool), the Markdown import gets it in as editable drafts:

Choose the target content type (pages or posts) and language, then upload up to 100 files in one batch (total size up to 40 MiB).
Each file can carry a YAML front-matter block at the top with title, slug, language, category, and meta description. Front matter is optional; when absent, the importer takes the title from the first H1 in the document (removing it from the body to avoid a duplicate heading) or, failing that, from the file name.
Everything converts to HTML at import, and any remaining top-level H1s inside the body are demoted to H2 so the page structure stays valid in the editor’s heading system.
Everything imports unpublished: review the results screen (it lists per-file success/errors), then publish when satisfied.
Slug collisions are handled automatically (my-page-2, etc.); conflicts within the batch never silently overwrite.
Front matter must be flat key/value lines: a nested list under title: is rejected with a specific error naming the field.
Malformed front matter fails just that file; the rest of the batch proceeds.
If the server is missing the optional Markdown pipeline modules, the import form tells you before you select files (an admin can install them).

Structured imports (JSON)

For a machine-produced migration (from an export, from a custom script, or from the API), use JSON imports:

Each content area you can export (pages, posts, categories, nav, documents, redirects, media, and more) accepts an array-of-objects file with that entity’s fields.
Up to 5,000 rows per import and a 4 MiB file.
A preview step shows per-row results before anything is written.
On the real import you can choose to update existing items instead of only creating new ones, keying is per-entity (pages keyed on slug+language, categories on name+language and slug+language, etc.).
Rows are validated against site languages and your own per-language permissions before insertion.

Bulk creation from a list

For quickly creating many short items (a batch of simple pages), the bulk-create screen accepts a pasted list of titles/content and creates them all, with slug-collision suffixes applied the same way as the Markdown importer.

Exporting your content

Full fields, JSON or CSV: the pages list and posts list each offer JSON (the complete content record, body, SEO fields, scheduling, translation keys) and CSV exports; both can be filtered by language and published/draft state, and individual items can be exported alone.
Auxiliary exports: categories, navigation, documents metadata, redirects, and media metadata each have their own export; users, the audit log, and your scheduling calendar offer CSV and ics downloads where appropriate.
CSV files carry a UTF-8 byte order mark, so they open cleanly in Excel.
Exports include only what your account is allowed to manage; editors export their own content scope.

All of these exports describe metadata and text. Media files, document files themselves, and the database in full are covered by backups; see Backup & Recovery.

Migrating safely

Export from the old source (JSON from a prior Chinaski instance or CSV from a spreadsheet).
Import via the matching route with preview enabled; read the per-row results.
Run the real import with update-existing enabled if you’re re-running after fixing issues.
Everything ends up as content: imports never delete anything, so broken rows can never erase what’s already there; you clean up manually.
Rebuild the site after a large import (imports can trigger it; very large batches can run as background jobs with progress tracking via the API).

For very large operations

The REST API accepts batch jobs: submit the item list, then poll job status (progress, errors, results) rather than holding a browser open. The bundled MCP server exposes these as tools for AI-assisted batch work.

What in/out looks like

Everything crosses in Chinaski’s own JSON shape (or columnar CSV); there is no WordPress-style WXR/proprietary dialect importer: JSON in, JSON out, the same shape on export as on import. Practically: your content is never trapped; take the JSON out, transform it however you like, bring it back, or just back up the whole instance.