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
.atlasprojectfile 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 inWebpages/, 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
.atlasprojectfile, 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.