Atlas Project Files

When you export a whole project, Atlas writes it as an Atlas Project file — a .atlasproject document. Unlike a PDF or ePub, which is a finished, read-only copy of your work, a project file is a complete, faithful snapshot of the project itself: every document, folder, canvas, sketch, and piece of media, along with the structure, tags, icons, and notes that tie them together. It's the format to reach for when you want to back up a project, move it to another device, or hand the whole thing to someone else running Atlas.

Bundle or Folder?

When you export a project you'll choose between two shapes for the same contents:

• Atlas Project Bundle — A single .atlasproject file that's easy to share, back up, or re-import. On Mac and iOS this looks and behaves like one file, even though it's a package underneath.
• Folder — The identical contents written as an ordinary, browsable folder. Choose this when you want to open the pieces yourself, read the raw markdown, or feed the files into another tool or a script.

Both options write exactly the same structure inside. The bundle is simply that folder wrapped up as a tidy, single-file package — pick whichever is more convenient for what you're doing.

What's Inside

A project file contains a plain-text index called manifest.json plus a set of folders holding your actual content, each grouped by type:

My Project.atlasproject/
├── manifest.json          The index: project info + every document
├── project-cover.png      Cover image (if the project has one)
├── Documents/             Text documents, as Markdown (.md)
├── Folders/               Folder structure (organization only)
├── Media/                 Images, audio, and other attachments
├── Canvas/                Canvas documents (.canvas)
└── Sketches/              Sketches (.drawing)

Only the folders you actually use appear — a text-only project won't contain a Media or Canvas folder. A few details worth knowing:

• Your writing stays readable. Text documents are exported as standard Markdown you can open in any editor.
• Metadata rides along. Custom fields and their definitions are recorded in the manifest, and each text document also opens with a YAML frontmatter block so other tools can read its title, tags, and field values.
• Media keeps its original name. Attachments are copied out under the filenames they came in with, so a photo called sunset.jpg stays sunset.jpg.
• Trashed items are left out. Anything in the trash at export time isn't included.
• Nothing is lost to duplicates. If two documents share a title, Atlas automatically numbers the files so they never collide.

The Manifest

manifest.json is the heart of the format. It's a human-readable text file that records everything Atlas needs to rebuild the project exactly as it was — the project's title and author, and for every document its title, type, position in the outline, tags, synopsis, notes, icon, and any custom metadata values — with the project's metadata field definitions stored alongside. The content folders hold the files; the manifest holds the structure and meaning that connects them.

Because the manifest is standard, openly documented JSON, a project file isn't a black box. You (or another program) can read it to see precisely what a project contains without needing Atlas at all.

Re-importing a Project

Bringing a project file back into Atlas is straightforward:

• On Mac — Double-click the .atlasproject file, or drag it into Atlas. You can also open a Folder export the same way.
• On iPhone & iPad — Tap the file in the Files app, or use Atlas's project browser to import it.

Atlas reads the manifest, recreates every document and folder in the right order, restores your tags and metadata, and copies the media back in — reconstructing the project as a fresh copy. Because export and import use the same format, a project file always round-trips cleanly.

Technical Reference

The rest of this page documents the manifest.json schema in full. Most people never need this but it's here for anyone writing tools that read or generate Atlas Project files.

File Layout

A project file is a package (or folder) conforming to the Uniform Type Identifier dev.contagious.atlas.project_bundle, which conforms to com.apple.package. Its layout is:

All file references in the manifest are relative paths from the package root. Subdirectories are created on demand, so only the folders in use are present.

Manifest Schema

manifest.json is UTF-8 JSON. Dates are ISO-8601 strings. The top-level object has three keys:

project object

documents[] entries

documentType values

Metadata

When a project uses custom metadata fields, the manifest carries both the field definitions and each document's values. The manifest is authoritative — Atlas restores metadata from these keys on import. (The YAML frontmatter written into Documents/*.md is a convenience for external tools and is ignored when re-importing a project.)

project.metadataDefinitions[] entries

documents[].metadata[] entries

A value whose field has no matching definition is imported as a new Text field.

Example

A minimal manifest with one folder containing one document:

{
  "version": "1.1",
  "project": {
    "title": "My Project",
    "author": "Jane Doe",
    "dateCreated": "2026-01-15T09:30:00Z",
    "image": "project-cover.png",
    "metadataDefinitions": [
      { "name": "POV", "type": 0, "sort": 0 },
      { "name": "Status", "type": 2, "selectionOptions": ["Draft", "Final"], "sort": 1 }
    ]
  },
  "documents": [
    {
      "uri": "doc-folder-1",
      "filename": "Folders/Chapter One",
      "title": "Chapter One",
      "documentType": 1,
      "tags": [],
      "sort": 0,
      "rootLocation": 0
    },
    {
      "uri": "doc-scene-1",
      "filename": "Documents/Opening Scene.md",
      "title": "Opening Scene",
      "documentType": 0,
      "synopsis": "The story begins.",
      "tags": ["Status > Draft"],
      "metadata": [
        { "field": "POV", "value": "Alice" },
        { "field": "Status", "value": "Draft" }
      ],
      "parent": "doc-folder-1",
      "sort": 0
    }
  ]
}