Files
Everything you write is Markdown and images. A campaign leaves as a package: a single .zip bundling its articles and images, with a manifest.json describing what's inside. Getting work back in needs no package at all, since Sync folder takes a plain folder and reads it as it is.
Packages follow the same principle as everything else: plain Markdown is the source of truth. Articles travel as ordinary .md files, images as their original files, and the manifest as plain JSON, so a package is readable in any tool and stored however you like.
Exporting
From a campaign's Articles → Control panel → Export, download a package of your content: your articles, including private and secret passages, since an export is always full-fidelity, plus the images you uploaded. The file is named gmtales-package-<campaign id>-<timestamp>.zip.
An export writes one images folder. A package with a separate portraits folder still imports: those images arrive labelled portraits.
A package holds only the exporting author's work. In a multi-author campaign there is no single whole-campaign backup; each author exports their own.
The sync.json file
An export also writes sync.json at the root of the package, beside the manifest. It records when you exported and, for each article that has a key, which version you took your copy from.
That is what lets a later upload tell you the article changed on the site while your copy sat on your machine. Without the file an upload has nothing to compare against and simply takes what you give it.
Keep it with the files you edit. If you sync a folder rather than a package, put sync.json in the folder you pick, and it does the same job there.
Articles with no key are not in the file, because a key is what the upload matches them by. They still come back, matched by title instead, but nothing tells the upload which version they left as.
Importing
Articles → Control panel → Import brings a package back in, in one of two modes; a plain folder works in place of the .zip.
Both modes have the same choice, ticked to begin with: Land as drafts. Leave it ticked and nothing you upload reaches the campaign until you say so — every article arrives as a draft, yours to read and publish one at a time or all at once, on the review page. Untick it to publish everything as it arrives.
Sync — re-import your own work
Sync restores a package or folder you exported, for example after editing the Markdown offline. Each file finds its article by key, or failing that by one of your articles with exactly the same title, drafts included; a file matching neither creates a new article.
An image whose file name already exists is left untouched, so edits made in the app are never clobbered, and genuinely new files are added. Sync continues past errors and reports the outcome of every file.
An uploaded article is read the same way one typed into the editor is: what the editor would refuse about the text, an upload refuses too, and the file is reported with every problem in it. The checks that ask what your campaign holds — an image the article points at, a group it names — stay with the editor, because a package carries its own images and they are not in yet when it is checked.
A key that belongs to an article another member wrote is a validation error for that file alone: GMTales names the key, and you change it in the file or ask its author to sync it themselves. Nobody may write over anyone else's article, here as everywhere.
Import — merge someone else's pack
Import brings in a package from someone else. The whole package is validated before anything is written, so a key clashing with an existing article, a reference to a group your campaign doesn't have, a malformed article, or an already-taken image name fails the import whole, with a list of exactly what to fix.
Only a wholly clean package gets through, and what gets through lands as drafts like anything else, so a pack you have never read is something you look at before your table does.
Syncing a folder
Articles → Control panel → Sync folder takes a plain folder instead of a .zip: pick a folder of Markdown articles and images, and it is read with the same matching rules as Sync. A few things are folder-specific:
An image's description and directives travel in a sidecar file with the same name beside it.
Images inside a folder named
portraitsarrive as portraits; every other image is a normal one.Files that are neither Markdown nor images are ignored.
Keep the
sync.jsonan export writes in the folder; without it, no conflict can be reported.
Reviewing an Upload
When an upload finishes it links to Review this upload, and that page is where the work gets published. It lists every file the upload touched, with what happened to it:
Badge | What it means |
|---|---|
Drafted | Saved as a draft over an article that is already published. The campaign still reads the published text. |
New draft | A new article that is nothing but its draft. Nobody but you can reach it yet. |
Draft replaced | You already had a draft open on that article, and this upload wrote over it. The old draft is gone. |
Unchanged | The file says exactly what the article already says, so nothing was written and nothing of yours was thrown away. |
Created | A new article published as it arrived, from an upload with the drafts box unticked. |
Updated | An existing article published over as it arrived, from an upload with the drafts box unticked. |
Skipped | Nothing to do. An image already in the campaign reports this. |
Error | That file was a validation error. The reason is in the Details column. |
Each row that still has a draft waiting has Compare, which puts the published version beside your draft, Publish, and Discard.
Across the whole upload, Publish all publishes everything that is not in conflict, Publish all, conflicts included takes the conflicts too, and Discard all throws every draft away. Discarding takes with it any article that was never published, since a draft is all such an article is.
You do not have to finish in one sitting. Earlier uploads below the import form lists what you have uploaded before, how many drafts are still waiting on each, and how many are in conflict.
Keeping your own copy in step
An upload marks a row Conflict when the article on the site is no longer the version you exported from. It means you changed it here after taking your copy away. GMTales says which of the two happened:
You have published this article here since you exported it.
The version you exported from has been removed.
A conflict never stops anything. The draft is written either way, because the article is yours and only you can resolve it. Compare the two, then publish or discard.
Exporting a draft, editing it offline and publishing nothing here in the meantime is not a conflict. Neither is an upload carrying no sync.json, which simply has no earlier version to measure against.
One sync.json per upload: pick the campaign's own folder, not a folder of folders. Two copies of the file at the same level say two different things about the same articles, so the sync fails rather than choosing between them, as does a file that is empty, is not valid JSON, or names the same key twice.
Partial packages
A package may contain any subset of sections: an articles-only pack imports without images, an images-only pack without articles. An upload reads whichever sections it finds.