Import and Export

Updated: 2026-09-09

This guide explains supported import/export workflows for recipes and informational cooking content.

Basic rule

Imports are previewed before saving. Imported values populate the normal editor so they can be reviewed and corrected before save.

Standing fidelity rule:

Export every populated value the target format can reasonably represent. Import every usable value present in the source. Omit blank values instead of exporting empty placeholders. Prefer blank over invented or misclassified data.

Canonical import architecture

All import paths normalize into the same application-level recipe shape and reuse the existing duplicate/review/editor flow:

source or external format
    -> acquisition/OCR or narrow format adapter
    -> canonical native recipe data
    -> duplicate/review handling
    -> normal Add Recipe editor
    -> explicit Save/Overwrite

Do not create independent autosaving importers for each external recipe program. The one deliberate exception is a user-confirmed bulk import of Recipe Site's own native multi-export collection, which reuses the normal native parser and recipe save path for each selected item rather than inventing a separate data path.

Import media lifecycle

Temporary imported media uses tokenized staging under /assets/images/import/{token}/ (and equivalent tokenized audio/video staging where applicable). Staging is temporary workspace data, not the permanent media location.

When a reviewed imported draft is explicitly saved as new content, referenced staged images are promoted/copied into the canonical per-content directory:

/assets/images/recipes/{id}-{slug}/

The same permanent media lifecycle applies to recipes and informational content such as guides, tips, techniques, and references. Do not create permanent named guide/tip/technique folders under /assets/images/import/. The product does not use a separate /assets/images/guides/ lifecycle.

Abandoned tokenized staging may be cleaned only when it is old, unreferenced by active sessions/database content, and otherwise passes the conservative cleanup rules.

Native/portable formats

The native importer accepts pasted native JSON, .recipe.json, .ddr, legacy .recipe-package.zip, and Recipe Site multi-export ZIP collections containing top-level .ddr packages.

.ddr is the preferred portable format and can carry referenced image/audio bytes in addition to recipe.json and manifest.json. Recipe Site multi-export ZIPs open as a selectable collection: every recipe is selected by default, individual recipes can be deselected, and Import Selected imports the chosen recipes in one operation. Preview opens any one item through the normal editable import draft before saving if inspection is wanted. Bulk native collection import never overwrites an existing matching recipe; matches remain for individual review.

The Add Recipe file picker accepts one or several files. Multiple files are uploaded sequentially and collected into a review queue. Large files are transferred in 20 MiB HTTP chunks and assembled in temporary session-owned server storage before format detection, which avoids common reverse-proxy per-request limits such as Cloudflare's 413 ceiling. Individual recipe/source files remain limited to 150 MB; Recipe Site collection ZIP transport is limited to 1 GB and 500 contained DDR packages. Temporary upload/batch data expires after six hours.

Supported content types are recipe, tip, guide, technique, and reference.

General source importer

Accepted source inputs:

• pasted plain text or HTML;
• public HTTP/HTTPS recipe URL;
• TXT/HTML/HTM/RTF/DOCX/legacy DOC;
• PDF, including text PDFs and scanned PDFs through local OCR;
• JPEG/PNG/WebP recipe images through local OCR.

Image sources may be chosen, dropped, or pasted. Firefox clipboard-image paste is explicitly supported.

Word documents

DOCX text extraction preserves high-confidence ingredient subsections, descriptive yield, instruction headings/options, flavor variations as notes, explicitly labeled recipe-level times, and later second-recipe boundaries. Legacy binary .doc files are extracted with the small local antiword utility and then use the same shared parser; no office suite is required.

URL

URL import prefers Recipe JSON-LD for core fields. When JSON-LD is absent, explicit visible Ingredients plus Directions/Instructions DOM blocks are protected first, removed from a working copy before broader remainder parsing, then merged back as the authoritative ingredient/instruction lists. URL import also preserves visible Level/Difficulty when available and can safely stage one high-confidence hero image from JSON-LD/Open Graph. External site taxonomies are not silently mapped into local categories.

OCR

Local English Tesseract accepts validated JPEG/PNG/WebP and scanned PDF pages. OCR is draft assistance, not source truth. OCR/PDF acquisition text is shown in an editable review step before parsing, and scanned sources support Automatic, Single column, and Two columns (left then right) reading order.

External recipe-program importers

External program adapters follow the same canonical preview/editor/save architecture. They must not autosave.

MasterCook

MasterCook support is now broader than the original MX2 work. The implementation deliberately separates interchange formats from MasterCook's native internal cookbook/image formats.

Current support matrix

Relevant completed work was merged in PRs #141, #151, #152, #153, #155, and #157.

Import front door and format detection

The unified MasterCook importer identifies supported formats rather than treating everything as MX2. Direct MX2, MXP/TXT, MZ2, and MC2 are supported. Generic ZIP collections can contain supported MX2/MXP/MC2 data. MCX, MCF, and MRF are recognized accurately even where full decode is unavailable.

Oversized PHP POST handling is separated from CSRF handling so large/unsupported collections report the real problem rather than a misleading invalid-token message.

MX2

MX2 supports both import and export.

Representative supplied mx2.dtd and real collections established important compatibility behavior:

• legacy ISO-8859-1 and Windows-1252 handling;
• formally malformed-era XML declarations where standalone precedes encoding;
• multi-recipe XML documents;
• foreign categories that must not silently become local categories;
• named MasterCook ratings/distinctions;
• Natn, CpyR, alternate times/sources, serving instructions, wine suggestions, and recipe/component references;
• an observed INtI / IntI spelling inconsistency.

Ingredient row semantics in inspected material:

• I = normal structured ingredient;
• S = ingredient section heading;
• T = free-text ingredient-list row;
• R = recipe/component reference.

Third-party files sometimes misuse a plain colon-ended T row as a heading. The importer treats it as a heading only when no quantity/unit/preparation/note data is present. Export emits native headings as proper code="S" rows.

MX2 export uses conservative DTD-era element order, ISO-8859-1 with XML character references where required, structured ingredient/direction/note content, source/author/cuisine/copyright/times, representable serving/annotation/wine data, and preserved named MasterCook ratings where available.

RTxt is not treated as a second authoritative recipe copy; structured recipe data is authoritative.

MXP / legacy text

MXP import and export are live. The adapter parses/preserves visible text conservatively, including the legacy fixed-width ingredient ruler when present. It maps/preserves author, servings, prep time, description, source, yield, cuisine where represented, ingredients/preparation, directions, notes, and foreign categories as external metadata.

MXP export has an export->re-import regression covering Unicode title, author, servings, prep time, source, yield, cuisine, ingredients/preparation, directions, notes, and category metadata.

MZ2

MZ2 import and export are live. MZ2 is handled as a ZIP-like image-bearing MasterCook interchange container with MX2 recipe data plus referenced raster images.

Import:

• reuses the MX2 adapter;
• resolves main/direction image references safely;
• supports validated JPEG/PNG/WebP/GIF embedded media;
• stages generated/deduplicated media under the existing import path;
• enforces path, archive, file-size, raster-signature, dimension, and expansion limits;
• refuses ambiguous basename matching rather than guessing.

Export:

• packages generated MX2 with local referenced main/direction images;
• accepts only safely confined local /assets/images files;
• rejects traversal/outside-root sources;
• normalizes packaged images to JPEG;
• mirrors conservative MasterCook sizing: main image up to 500 px longest side and direction images up to 300 px.

Per-recipe MasterCook Auto selects MZ2 when the recipe includes a main or step image; otherwise it selects MX2.

Native MC2

Native MC2 recipe-data import is live. The adapter does not shell out to an old Windows converter and does not rely on proprietary MasterCook code.

The supplied native corpus established that MC2 recipe bodies use PKWARE Data Compression Library (DCL) implode, not PKZIP implode. The production PHP adapter independently implements bounded DCL decompression from the public format, validates expected expanded sizes, parses the native typed object/property structure, handles Macintosh Roman text, and maps usable recipe fields into the canonical recipe model.

Compatibility-corpus validation:

1,321 recipes
9,413 ingredient rows
2,800 direction steps
0 DCL record-decompression warnings

Native recipe record IDs are retained as source metadata so MCX companions can be associated deterministically.

There is intentionally no native MC2 writer. For transfer back to MasterCook, use MZ2/MX2/MXP interchange instead of manufacturing MasterCook's internal cookbook database.

MCX native photo companions

MCX file structure and recipe association are understood enough to index the companions. Image records identify MPic main/full images and Thmb thumbnails. The second signed image-record ID matches the MC2 native recipe record ID.

Across the supplied compatibility corpus:

194 LEAD image streams
97 recipes with photo companions
all 194 streams matched MC2 native recipe IDs exactly

The remaining blocker is pixel decompression. Payloads are proprietary LEADTOOLS LEAD CMP raster data. Standard Linux ImageMagick, Pillow, and ffmpeg tooling does not decode them. LEADTOOLS provides its own codec/runtime and requires a licensing/runtime decision.

Do not silently install a proprietary/evaluation codec in production. If recovering old MCX photos becomes important, make that dependency decision explicitly.

Some MC2 directions contain DirP picture references, but direction-image mapping must not be invented until the image payload/relationship can be validated end to end.

MCF/MRF

MCF/MRF are detected as old MasterCook native formats but are not parsed. No trustworthy representative sample/spec has been available. Do not implement from guesswork; obtain real samples first.

MasterCook ratings and external metadata

Favorites remain separate from ratings.

Per-user ratings are whole 1–5 stars. Imported scalar MasterCook ratings may seed an external/average value, import as the current user's rating, or be ignored according to the owner default and per-recipe import choice. Named distinctions such as Family Favorite or Finalist/Award Winner are preserved but are not guessed into star ratings.

Source-scoped external metadata preserves MasterCook-only information useful for provenance and round-trip behavior without adding a dedicated site column for every old field.

Multi-recipe export

All Recipes provides an export selection mode for accounts with recipe-export permission. Choose Select Recipes to Export, select individual published recipes or use Select All, then export the selection as:

• Recipe Site (.zip) — an outer ZIP containing one lossless .ddr package per selected recipe, including the media that each DDR can carry;
• MasterCook MXP collection;
• MasterCook MX2 collection.

Select All replaces the older always-visible Export all links. The current collection guard is 500 recipes per request.

MasterCook regressions

Current dedicated tests include:

tests/mastercook-mx2-roundtrip.php
tests/mastercook-format-detection-mxp.php
tests/mastercook-mz2-import.php
tests/mastercook-mc2-import.php

The final compatibility work also validated MZ2 export, MCX indexing, MXP export/round-trip, and collection export in the production PHP image. Do not claim support for untested MasterCook generations beyond representative evidence.

Paprika Recipe Manager

Paprika import is live.

Supported formats:

• .paprikarecipe — single GZIP-compressed JSON recipe;
• .paprikarecipes — ZIP collection containing gzipped recipe entries.

The adapter preserves where present:

• name and description;
• servings;
• prep/cook/total time;
• source and source URL;
• raw ingredient lines;
• directions;
• notes;
• nutrition text and recognized nutrient values;
• difficulty/provenance metadata;
• Paprika categories;
• Paprika rating metadata;
• supported embedded JPEG/PNG/WebP/GIF photos.

Paprika categories remain source metadata and are not silently created or mapped to local categories. Paprika's 0–5 rating is treated as a personal rating; selection/review can import it as the importing user's rating or ignore it. It is not converted into a fake community average.

Collection safety limits include per-entry compressed/expanded limits, archive-entry and recipe-count limits, aggregate compressed-data limits, image validation, and a 180 MiB aggregate expanded recipe-data limit. Corrupt individual recipes may be skipped with warnings, but an aggregate expansion-limit breach aborts the collection.

Regression:

tests/paprika-import.php
PAPRIKA_IMPORT=PASS

A real user-generated Paprika export would still be useful as an additional compatibility audit for unusual field/photo/category cases.

Meal-Master

Meal-Master import and export are supported for the long-lived plain-text interchange family used by the DOS-era program and later recipe managers.

Import accepts .mmf, .mm, and .txt files. A single file may contain one recipe or many concatenated recipes. The adapter recognizes common MMMMM and Recipe via Meal-Master headers, classic fixed-column and two-column ingredient layouts, the relaxed spacing accepted by later Meal-Master 8 releases, ingredient continuation lines, dashed ingredient-section headings, and common DOS CP437 text. UTF-8 and best-effort Windows-1252/ISO-8859-1 decoding are also accepted.

Meal-Master categories are preserved as source metadata and are never silently converted into Desert Dog categories. Yield/servings, source extensions, ingredient preparation text, directions, notes, and recognizable unit codes are preserved where the source represents them. Multi-recipe files open a recipe chooser and each selected recipe then uses the normal duplicate/review/editor flow; nothing is saved automatically.

Per-recipe export produces a conservative single-column .mmf recipe following the published legacy limits: title at most 60 characters, at most five 11-character categories, 7-character amount field, 2-character recognized unit code, and 28-character ingredient text with proper continuation lines. Unknown modern units or values that cannot be represented safely are retained as ingredient text instead of inventing a bogus Meal-Master unit. Hyphen-only trailers are recognized correctly, headerless Title-based imports are tolerated, and relaxed count lines such as 2 Bay leaves or 1 Egg are not mistaken for unknown unit codes. Unicode fraction characters are emitted as ASCII fractions for compatibility. Export remains UTF-8 so current recipe text is not deliberately damaged; very old DOS software may display non-ASCII characters imperfectly even though the importer understands common CP437-era input.

Meal-Master is a deliberately lossy legacy target. It has no practical representation for Desert Dog media, rich content sections, ratings, nutrition detail, or many modern metadata fields. Use DDR for full-fidelity Desert Dog transfer and MZ2/MX2 when richer MasterCook interchange is required.

Regression:

tests/mealmaster-import-export.php
MEALMASTER_IMPORT_EXPORT=PASS

Because no original user-generated Meal-Master archive is available, support is validated against the published format conventions and representative synthetic fixtures rather than claiming every historical third-party variation.

Recipe Keeper

Recipe Keeper import is supported for the application's ZIP export and for an extracted recipes.html file. The normal ZIP is preferred because it also carries photos. Public implementations and current Recipe Keeper migration documentation independently establish the export shape as recipes.html plus an images/ directory, with each recipe represented by a .recipe-details block and Recipe Keeper-specific itemprop fields.

Import preserves where present:

• title and description;
• yield/servings;
• prep and cook times;
• source name and source URL;
• raw ingredient lines;
• directions and notes;
• personal 0–5 rating metadata;
• Favorite state as source metadata;
• Recipe Keeper categories, courses, and collections as external metadata;
• recognized nutrition fields;
• validated JPEG/PNG/WebP/GIF photos referenced by the export.

Recipe Keeper taxonomies remain external metadata and are never silently converted into Desert Dog categories. Personal ratings can be imported as the current user's rating or ignored. ZIP handling is bounded by upload, entry-count, per-entry, total-expanded-size, path, raster-size, raster-dimension, and image-type checks; the archive is read directly rather than extracted blindly.

Per-recipe export creates a Recipe Keeper-compatible ZIP containing recipes.html and any safely referenced local recipe photos under images/. It uses the same Recipe Keeper field vocabulary observed in independent importers, including recipeId, recipeIsFavourite, name, yield, prep/cook times, source, categories, ingredients, directions, notes, nutrition, and photo classes. Desert Dog-only fields that Recipe Keeper's observed interchange has no clear representation for are omitted rather than invented.

Regression:

tests/recipekeeper-import-export.php
RECIPEKEEPER_IMPORT_EXPORT=PASS

No original user-generated Recipe Keeper archive or installed Recipe Keeper application is available for an application-to-application round trip. Import compatibility is grounded in multiple independent open-source importers/documentation and synthetic fixtures. For that reason the outbound option is labeled Recipe Keeper-compatible until a real Recipe Keeper import confirms the generated ZIP end to end.

Subsequent adapters

No additional external-program adapter is currently selected. Add another only when there is a real user need plus a stable documented/exportable format or representative files. Generic CSV/XML/JSON support should not be added merely for format-count completeness.

URL/image security

Public URL and remote-image handling must keep HTTP/HTTPS-only restrictions, no embedded credentials, rejection of localhost/private/reserved/internal targets, DNS/public-IP validation/pinning, redirect revalidation, protocol/time/size limits, safe content-type checks, raster MIME/signature/dimension validation, generated filenames, and no SVG/executable uploads.

Do not weaken SSRF protections to work around a public site returning 403.

Import preview requirements

Every importer should:

1. acquire/validate exactly the intended source;
2. decode/extract the source format safely;
3. normalize into canonical native recipe data;
4. capture every recognized usable field;
5. preserve source provenance and original wording where uncertain;
6. detect likely duplicates;
7. stage media only when applicable and safe;
8. resolve existing local categories/tags only when justified;
9. populate the normal editor;
10. require explicit review and Save/Overwrite.

Field meanings

• subtitle: concise tagline/blurb.
• description_short: short summary/context.
• story: longer narrative/context.
• servings: people/portions only.
• yield_text: descriptive yield such as 24 pierogi.
• cuisine_nationality: cuisine, regional tradition, or nationality associated with the recipe.
• copyright_text: copyright/permission/rights statement from the recipe source.
• source organization/site maps to Source Name; creator/adaptor maps to attribution.

Do not derive recipe servings from a nutrition serving size or item count unless the source explicitly states servings.

Categories during import

Use existing canonical categories only. Do not silently create categories from outside taxonomy. Exactly one strongest primary category should be chosen, with all valid secondary categories and no weak/invalid mappings. Method categories must be supported by content, not title alone.

Vegetarian/Easily Adapted means vegetarian already or made vegetarian through simple substitutions such as broth/fat. Replacing the main meat/protein with tofu/fake meat does not qualify.

Notes, sections, Unicode, and multiple recipes

• Preserve note type/text and section type/title/body.
• Advisory/storage/substitution prose should not become instructions.
• A complete second recipe should remain separate content.
• Unicode fractions are valid; do not reintroduce byte-mode line splitting that corrupts UTF-8.
• Extra-section image markers are positional and render where they occur.
• Unsupported informational section types must not be silently discarded; preservation/normalization needs continued hardening.

Representative testing

Testing should include native JSON/DDR, text/HTML/RTF/DOCX, browser-sensitive URLs, multiple JSON-LD objects, remote image staging, URL security blocking, OCR choose/drop/paste, Unicode fractions, ordered section images, duplicate handling, and no-autosave behavior.

External-format adapters additionally require representative real files from each claimed version/variant. Use focused synthetic/derived fixtures where possible rather than committing large copyrighted recipe collections.

For package/media imports, verify filesystem bytes and public URLs, not Git status alone.

Remaining import/export work

• Run a real Recipe Keeper application round-trip when an original export/application becomes available; keep outbound wording as Recipe Keeper-compatible until then.
• Obtain an MCF/MRF sample before attempting old native MasterCook parsing.
• Decide explicitly whether MCX photo recovery justifies a proprietary LEADTOOLS CMP dependency.
• Run a real-user Paprika compatibility audit when an export is available.
• Add field-level import confidence/warnings where useful.
• Add OCR text review before parse.
• Continue generalized section-preservation and source-provenance hardening.

Do not claim outside-format compatibility until representative files have passed end to end.