Importing and exporting
Sgeulai is not trying to be the last place your book ever lives. Everything comes in and everything goes out.
Bringing work in
Import Project Backup… is the one way in that isn't
here — it lives in the File menu, because it replaces a project rather
than adding to one.
| Command | What it does |
|---|---|
| Import Scrivener Project… | Brings the binder structure across along with the text. |
| Import EPUB Manuscript… | Splits a finished EPUB back into chapters. |
| Import Plottr File… | Reconstructs the manuscript along with the plot lines you had planned. |
| Import Aeon Timeline File… | Reads an Aeon Timeline 3 project — its people, places, events and typed links, each date at its own precision — and its narrative as outline chapters. |
| Import Bibliography (BibTeX / CSL-JSON / EndNote XML)… | Fills the Source records for research-heavy work — EndNote XML is what EndNote exports and what Bookends writes for File ▸ Export References. Beside it, Link a Synced Bibliography File… and Refresh Linked Sources keep those sources current. See Notes & citations. |
| Import Manuscript (from Another Project)… | Merges one manuscript from another Sgeulai project's export into this one — see below. |
| Import Highlights (Apple Books)… | Reads a backup exported by the Highlights app — see Research Highlights. |
| Import Project Backup… | Restores a whole project from a backup file. In the File menu. |
Every import above runs the same way: pick the file in a standard Open panel, and the import runs immediately — no options screen, no "review before committing" step. A single alert reports what came in by the numbers, and that's the whole interaction.
What each import actually reads
Import Scrivener Project… reads the .scriv
package's own binder file directly — the same XML Scrivener itself writes —
rather than guessing structure from folder names. Three levels of nesting
in the binder becomes Part → Chapter → Scene; two levels gets disambiguated
by title (a document titled "Part One," or most of a level's children
literally titled "Chapter…") before falling back to a flatter reading.
Per-document word-count targets, revision status from Scrivener's own
status-definitions table, and whatever sectionpurpose/
globalpurpose/valueshift custom metadata fields you
set up in Scrivener come in too, not just the prose.
Import Plottr File… reads a .pltr file,
which is already plain JSON — Plottr's own export format, not something
Sgeulai has to reverse-engineer. Characters and places become Character
and Location records, with Plottr's own custom character fields mapped
across; plot lines become Story Arcs, and the cards on them become arc
beats. The one genuinely clever part: Plottr has no manuscript field of its
own — writers who draft inside it do so in a card's description, one line
at a time. So Sgeulai reconstructs a manuscript from the timeline's row
order (Plottr's closest thing to a table of contents), taking whichever
card on each beat — across every line — carries the most text, on the
reasoning that the richest card at a position is the actual draft and the
others are outline notes about the same moment. Each non-empty beat becomes
one chapter; nesting into scenes isn't attempted, since how a Plottr file is
organized varies too much to infer reliably.
.pltr — Plottr's templates carry their own title into every
book started from one, so years of work can otherwise arrive under a name
like "STC-60-Scene-Novel-Template." And the import
switches you to that manuscript when it finishes:
everything it creates belongs to its own book, so with a manuscript scope
already set — the ordinary state — the whole import would otherwise be filed
under a book nothing on screen is showing, with no chapters in the binder
and every Story Bible count still reporting the old book. If an import ever
appears to bring in nothing, check the Working on picker
first.
The name in the alert is the file's, which is why it
is worth naming a .pltr properly before importing it. The alert
also tells you it has switched you to the new manuscript, and where the
material landed.
Import EPUB Manuscript… reads the EPUB's own package
file — the spine gives reading order, and each spine document becomes one
chapter, in the order the book itself declares, not by guesswork. An
<h1> names the chapter; horizontal rules mark scene
boundaries, which is exactly what Sgeulai's own EPUB export writes and close
to what most EPUB producers write. Two things an EPUB genuinely can't
carry: which sections are front or back matter (checked against a list of
standard trade-book titles — "Dedication," "Copyright,"
"Acknowledgments," and similar — with anything unrecognized treated as
body prose, since mislabeling a real chapter as front matter would knock
out its numbering), and scene names, which come back as "Scene 1," "Scene
2." This one runs with a progress sheet rather than blocking the window,
because it also auto-links every Story Bible name it finds across the new
prose once the chapters are in.
You can also import facts into a single record from Wikipedia, from the record's own sheet — useful for historical figures and real places.
Taking an import back out
Import History…, at the bottom of the Import menu, lists every import into this project, newest first: the file, the importer, when, and what it created. Scrivener, EPUB, Markdown and Word, Plottr, Aeon Timeline, bibliographies, Sgeulai Manuscripts and project files are all recorded. Highlights and History CSV imports have their own ways back and aren't listed, and imports made before this history existed can't be.
Revert… moves the records the import created to the Trash, so a revert can itself be undone by restoring them. Before it does, it says how many will go. A record you've edited since the import (its name, summary, details, notes or prose) is kept and named. Relationships and dates the import added to records that were already here are deleted, and a backup is saved first. The manuscript itself stays, empty, so chapters restored from the Trash have somewhere to go.
Sending work out
The Export button in the editor toolbar (the arrow-out-of-a-box icon) holds thirteen commands, each writing straight to a save panel using whatever is already configured in Settings — no intermediate dialog to fill in first.
Preview Manuscript… is separate from these thirteen — see its own subsection below — even though it shares the toolbar. The thirteen proper:
The two dividers are the whole map: manuscript formats
in the middle band, everything that is not a manuscript at the bottom.
| Command | For |
|---|---|
| Export ePub (Styled) | A readable EPUB. The only EPUB export there is; there is no plain/unstyled variant. |
| Export Manuscript (PDF) | Standard manuscript format — Letter trim, one-inch margins, deliberately unbranded — for submission. |
| Export for Vellum (DOCX) | Styled for Vellum's own importer to recognise, with no table of contents field — Vellum builds its own front matter from the heading structure. |
| Export to Scrivener… | A manuscript nested by Part, going back out as a .scriv package — see below. |
| Export Manuscript (DOCX) | The same Word file, but with a real, clickable table of contents — for an editor who wants to navigate a Word document directly. |
| Export Tracked Changes (DOCX)… | A Word file carrying your own edits as tracked revisions, for an editor who will accept or reject them and send it back — see below. |
| Export Manuscript (RTF) | The manuscript-format PDF's page setup (trim, margins, page numbers) in an RTF file instead. |
| Export Manuscript (Markdown)… | A folder of Markdown, not a single file — one .md per chapter plus an index.md holding the whole book. See below. |
| Export Project Backup (JSON) | Everything, in a format you can read without this app. |
| Export Manuscript for Another Project… | One manuscript, on its own, to merge into a different Sgeulai project — see below. |
| Export Story Bible Reference… | A name-to-id catalog of this project's characters, locations, and other Story Bible records, for an outside tool building a file that links to them by id. |
| Export AI Provenance Report… | A PDF breakdown of how much of the manuscript carries an AI mark and of what kind — see Writing aids in the editor. |
| Export AI Disclosure Manifest (JSON)… | The same report as a JSON file a publisher's or contest's system can read, with where each passage sits — also in Writing aids in the editor. |
| Export Spoiler-Safe Canon… | A Story Bible PDF filtered to what a reader who's finished one book (and everything before it) is allowed to know — for a beta reader or collaborator. Disabled until the project has at least two books. |
.docx, but they are built to be read by
different things next: Vellum's own import step, or a person scrolling and
clicking a table of contents in Word. Pick the one for whoever opens it next
rather than by file extension.
[[wikilink]] inside
a known record's own text that points at one the reader isn't cleared for
is redacted to "someone," even when the link carries its own display name.
One picker and one sentence — the sentence is the part
worth reading, because "never marked at all" is on the excluded side.
Export Manuscript (Markdown)…
The one export that does not write a file. It writes a folder, and the save panel asks where to put it rather than what to call it — the single place this export behaves unlike every other on the menu.
Inside: one .md per chapter, numbered so they sort in reading
order, plus an index.md carrying the whole manuscript inline with
a linked table of contents above it. That means the folder reads correctly
either way — chapter by chapter for an editor working in pieces, or
index.md alone for anyone who wants the book as one document.
Pictures referenced from the prose land in an images/ subfolder
beside them, created only when something actually references one.
The numbers keep the chapters in reading order in any
file list.
Export Tracked Changes (DOCX)…
A Word file that carries your edits as real tracked revisions rather than
as finished prose, for the round trip where an editor accepts or rejects each
one and sends the file back. Importing that reply is the other half: if the
returned .docx still holds unresolved review markup, Sgeulai says
so on arrival and offers Review Changes…, which walks the
insertions and deletions one at a time.
Comments and revisions are counted separately.
Comments land as ordinary manuscript comments whatever you choose here;
only insertions and deletions need accepting or rejecting.
Preview Manuscript…
Opens a sheet with its own Styled/Manuscript-format toggle and its own Export menu — four outputs local to the preview, separate from the toolbar's: Export PDF (Styled)…, Export PDF (Manuscript Format)…, Export DOCX… and Export EPUB…. Reach for this when you want to see the page breaks and typography before deciding what to send.
Exporting to Scrivener
Export to Scrivener… is the same round trip in the other
direction from Import Scrivener Project…: a manuscript
nested by Part, going back out as a .scriv package.
Moving a manuscript into another project
Export Manuscript for Another Project… and Import Manuscript (from Another Project)… are a pair, and neither is the same thing as a project backup. Export writes just one manuscript — plus the Story Bible records that belong to it — to its own file; Import merges that file additively into whichever project is currently open, alongside whatever is already there. Nothing existing gets touched, and any reference the manuscript had to something outside its own scope (an entity that was never assigned to that manuscript) is dropped on import rather than pulled in — the import result tells you how many links were dropped, so nothing goes missing silently.
This is deliberately different from Import Project Backup…, which replaces every record in the currently open project with what's in the backup file. Use the manuscript export/import pair to move one book between projects; use a project backup to restore or clone a project wholesale.
Merging whole projects: Import Project Files…
One command on the Import menu is hidden. Click the toolbar's Import icon, then hold ⌃⌥⌘ (Control, Option and Command) while the menu is open, and Import Manuscript (from Another Project)… changes to Import Project Files… in place. Let go of the keys and the ordinary command is back.
Hold the keys after the menu opens, not before. With Control held, macOS treats the click as a right-click and shows the toolbar's own menu instead.
It takes .sgeulai project files — nothing needs exporting
first — and merges them into the open project. Pick several at once and they
merge one after another, with one alert reporting on each. From each project
you get:
- Every manuscript, with its chapters and scenes, added alongside the ones already here.
- The Story Bible, including records filed under no manuscript, which arrive filed under none.
- Relationships, including ones between records in two different books.
- The picture library, each picture still belonging to the book it came in with.
A record this project already has is reused, not copied. Same name and same type, and the arriving record becomes the one already here: it gains the new book in Appears In, and every link in the merged books points at it. Its fields are not combined with the arriving copy's — use Merge for that. The alert says how many records were matched. Chapters and scenes are never matched.
Your file is never opened in place. Sgeulai reads a private copy of it and throws the copy away, so it merges what is saved on disk — if that project is open in another window, let it save first.
Backups
A full project backup is written automatically before anything destructive — clearing a manuscript, replacing an AI analysis. Find them under Tools ▸ Show Automatic Backups.
What is not touched
Importing a manuscript does not take ownership of the file it came from.
Deleting a manuscript inside Sgeulai leaves the original .md on
disk exactly as it was.