Skip to content

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.

Info

Project exporting is always available, even after a subscription lapses. Atlas never holds your data hostage — a project file is an open, self-contained package that other tools can read, so your work is never locked in. See Exporting Your Work for the export basics.

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.

Tip

A .atlasproject bundle is a folder. On a Mac you can right-click one in the Finder and choose Show Package Contents to look inside without changing anything.

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)
├── Webpages/              Web pages, as .url shortcut files
├── Versions/              Saved versions of documents (from format 1.5)
└── Templates/             Templates, as Markdown (.md)

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. When you re-import, Atlas strips only the frontmatter it added itself. Frontmatter that was already in your document stays put, and the manifest records which case applies.
  • Web pages are real files. Each web page is written as an Internet Shortcut (.url) file in Webpages/, so you can double-click it outside Atlas to open the page.
  • Files get safe, unique names. Document, media, and web page names are sanitized for the file system and made unique, ignoring case, so two items that differ only by capitalization never collide. Media keeps its original filename recorded in the manifest.
  • Trashed items are left out. Anything in the trash at export time isn't included, and neither is anything inside a trashed folder. Canvas cards that point to a left-out document are skipped, and a connection between cards is exported only when both of its cards are.

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 overview, metadata field definitions, and every tag (with its order, color, and icon) stored alongside. Dates, canvas settings, and folder settings are recorded too. 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 — Choose File > Import Project > Atlas Project…, or double-click the .atlasproject file, or drag it into Atlas. You can also open a Folder export the same way.
  • On iPhone & iPad — Open the More (…) menu in the project picker and choose Import Project > Atlas Project…, or tap the file in the Files app.

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

A few safeguards protect you along the way:

  • If a project file was written by a newer version of Atlas than the one you're running, Atlas declines to import it and tells you why. Update Atlas and try again.
  • If an import fails partway, Atlas removes whatever it had created so you aren't left with a half-built project.
  • On export, Atlas builds the new file in a staging location and swaps it in only once it's complete, so a failed export never replaces your previous one.

Tip

This round-trip is a handy way to duplicate an entire project or move one between devices that aren't on the same iCloud account — export to a bundle, then re-import it wherever you need it.


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:

Path Contents
manifest.json Required. The project index (schema below).
project-cover.<ext> Optional. The project cover image (PNG or JPEG).
Documents/*.md Text documents, as Markdown.
Media/* Media attachments, sanitized and made unique. The original filename is recorded in the manifest.
Canvas/*.canvas Canvas documents.
Sketches/*.drawing Sketch documents.
Webpages/*.url Web pages, as Internet Shortcut files.
Versions/* Saved versions of text documents and sketches, one file per version (added in version 1.5).
Templates/*.md Project templates, as Markdown.
Folders/* Placeholder entries for folders (structure only; no content).

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 four keys:

Key Type Description
version String Manifest format version. Currently "1.5".
project Object Project metadata (see below).
documents Array One entry per document, folder, and media item.
templates Array? One entry per project template (added in version 1.3). Absent in older files.

project object

Key Type Description
title String The project title.
author String? The project author, if set.
dateCreated Date? Original project creation date.
image String? Relative path to the cover image, e.g. project-cover.png.
iconName String? The symbol name of a project icon created in Atlas. Written only when the cover is a created icon, not a photo. Optional, so the manifest version stays "1.4".
iconColor String? The color of a created project icon, as a hex string. Atlas restores iconName and iconColor on import only when the manifest also has an image, so the imported project reopens the icon sheet with the same choices.
metadataDefinitions Array? The project's custom metadata field definitions (added in version 1.1). See Metadata below.
tagDefinitions Array? The project's tag styling — color and icon per tag (added in version 1.2). See Tags below. Still written for older readers.
overview String? The project overview text, as Markdown (added in version 1.4).
tags Array? Every tag in the project, including tags attached to nothing, with sort order, icon, and color (added in version 1.4). See Tags below.

documents[] entries

Key Type Description
uri String A stable identifier for the document, unique within the manifest. Used to link parents and children. Replaced on import.
filename String Relative path to the document's file. For webpages, this is the path to the .url file (in manifests older than 1.4 it held the URL itself, which Atlas still imports). Empty for folders.
title String? The document title.
documentType Int The document's type (see the table below).
synopsis String? The document synopsis.
notes String? The document notes.
iconName String? The name of the document's icon.
iconColor String? The icon color, as a hex string.
tags [String] Tag titles. Hierarchical tags use "Parent > Child" format. Per-tag color and icon are recorded in project.tags (see Tags).
tagPaths [[String]]? Each tag as an array of names from the top-level tag down (added in version 1.4). Unlike the joined tags strings, these stay unambiguous when a tag name itself contains " > ".
metadata Array? The document's custom metadata values as {field, value} pairs (added in version 1.1). See Metadata below.
parent String? The uri of the parent document, for nesting. Omitted for top-level items.
sort Int Sort order among its siblings.
rootLocation Int? Placement for top-level documents (those with no parent).
mediaOriginalFilename String? For media documents, the attachment's original filename.
sketchCanvasBackground Int? For sketches: 0 transparent, 1 light, 2 dark.
sketchShowGrid Bool? For sketches: whether the grid is visible.
sketchGridStyle Int? For sketches: 0 dots, 1 lines.
url String? For webpages: the page URL (added in version 1.4).
frontMatterInjected Bool? For text documents: whether Atlas added the YAML frontmatter block at the top of the exported file. On import, only frontmatter Atlas added is stripped (added in version 1.4).
dateCreated Date? When the document was created (added in version 1.4).
dateLastEdited Date? When the document's content was last edited (added in version 1.4).
canvasLocked Bool? For canvases: whether the canvas is locked (added in version 1.4).
canvasShowsGrid Bool? For canvases: whether the grid is visible (added in version 1.4).
canvasGridStyle Int? For canvases: 0 dots, 1 lines (added in version 1.4).
canvasGridColor String? For canvases: the grid color, as a hex string (added in version 1.4).
showChildrenSynopsis Bool? For folders: whether the outline shows children's synopses (added in version 1.4).
showChildrenTags Bool? For folders: whether the outline shows children's tags (added in version 1.4).
excludedExportChildren [String]? For folders: the uri of each child excluded from export (added in version 1.4).
chapterMarkerChildren [String]? For folders: the uri of each child that starts an ePub chapter (added in version 1.4). Absent if the folder was never configured.
versions Array? For text documents and sketches: the document's saved versions, oldest first (added in version 1.5). See below.

documentType values

Value Type File location
0 Document Documents/*.md
1 Folder (none — structure only)
2 Media Media/*
3 Canvas Canvas/*.canvas
4 Webpage Webpages/*.url
5 Sketch Sketches/*.drawing

versions[] entries

Key Type Description
filename String Relative path to the version's snapshot file under Versions/.
title String? The version's name, if it has one.
dateSnapshotted Date When the version was saved.
deviceName String? The device that saved the version.

Export writes each version's snapshot to Versions/, leaves out conflict copies, and drops a version whose file can't be found, with a warning. Import recreates a version for each entry, and skips an entry whose file is missing.

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

Key Type Description
name String The field's name.
type Int The field type: 0 Text, 1 List, 2 Selection, 3 Number, 4 Boolean, 5 Date, 6 Date & Time.
selectionOptions [String]? For Selection fields, the available options in order.
sort Int Display order among the project's fields.
iconName String? The field's icon name.
iconColor String? The field's icon color, as a hex string.

documents[].metadata[] entries

Key Type Description
field String The field name, matched to a definition by name (case-insensitive).
value String The serialized value — JSON for lists, ISO-8601 for dates, plain text otherwise.

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

Tags

From version 1.4, project.tags is the authoritative list of every tag in the project, including tags that aren't attached to any document. Each entry records the tag's position, color, and icon, so tag order and styling round-trip on import.

project.tags[] entries

Key Type Description
pathComponents [String] The tag's names from the top-level tag down to this tag.
sort Int Sort order among sibling tags.
iconName String? The tag's icon name.
iconColor String? The tag's color, as a hex string, e.g. "#34C759".

Each document's tagPaths array uses the same path arrays, so a tag named "A > B" (one tag) is never confused with tag B under A (two names). The older tags strings, using "Parent > Child" format, are still written for older readers.

For compatibility, Atlas also still writes the older project.tagDefinitions array, which records color and icon keyed by the joined path.

project.tagDefinitions[] entries

Key Type Description
path String The tag's full path. Hierarchical tags use "Parent > Child" format, matching the strings in each document's tags.
iconName String? The tag's icon name.
iconColor String? The tag's color, as a hex string, e.g. "#34C759".

tagDefinitions carries styling only. Manifests from before version 1.4 have no project.tags, so for those files the list of tags comes from the tags arrays on documents. A tag with no matching definition imports without custom styling.

Templates

Version 1.3 added project templates. Each template is written to Templates/<Title>.md and listed in the top-level templates array. Template entries carry uri, filename, title, notes, iconName, iconColor, tags, sort, and metadata, and from version 1.4 also tagPaths, dateCreated, and dateLastEdited. Templates import verbatim, and {{token}} variables in the body stay live until you apply the template to a document.

Canvases

Canvas files use the open JSON Canvas format, so other tools can read them. Document cards point at project paths such as Documents/... or Media/..., and web cards stay standard link nodes. Pins keep their reference to the document they pin.

A card may also carry an atlasCard field with state only Atlas understands: whether the card is locked, how a document card displays, whether it hides its background, and the exported file path of the document it shows. Other tools ignore this field, and Atlas uses it to restore each card exactly on import.

Example

A minimal manifest with one folder containing one document:

{
  "version": "1.5",
  "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 }
    ],
    "overview": "A short novel in three parts.",
    "tags": [
      { "pathComponents": ["Status"], "sort": 0, "iconName": "flag", "iconColor": "#8E8E93" },
      { "pathComponents": ["Status", "Draft"], "sort": 0, "iconName": "pencil", "iconColor": "#34C759" }
    ],
    "tagDefinitions": [
      { "path": "Status", "iconName": "flag", "iconColor": "#8E8E93" },
      { "path": "Status > Draft", "iconName": "pencil", "iconColor": "#34C759" }
    ]
  },
  "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"],
      "tagPaths": [["Status", "Draft"]],
      "frontMatterInjected": true,
      "dateCreated": "2026-01-15T10:00:00Z",
      "dateLastEdited": "2026-02-01T18:45:00Z",
      "metadata": [
        { "field": "POV", "value": "Alice" },
        { "field": "Status", "value": "Draft" }
      ],
      "parent": "doc-folder-1",
      "sort": 0
    }
  ]
}

Compatibility

The version field lets Atlas evolve the format safely. Tools that read project files should check version and treat unrecognized keys leniently, since future releases may add fields. Atlas refuses to import a manifest whose version is newer than the one it supports and shows a message explaining why.

Version Added
1.1 project.metadataDefinitions and per-document metadata.
1.2 project.tagDefinitions.
1.3 Templates: the top-level templates array and Templates/*.md.
1.4 Web pages as Webpages/*.url files with a url field, project.overview, project.tags, tagPaths, frontMatterInjected, document and template dates, canvas lock and grid settings, folder outline and export settings, and the atlasCard canvas extension.
1.5 Document version history: the per-document versions array and Versions/* files.

Older files simply omit the keys their version predates and still import cleanly.