Import an Obsidian Vault

Scriptorium can import an entire Obsidian vault as a new project. The folder tree is mirrored, [[wikilinks]] become real page links with working backlinks, #tags become tags you can filter by, callouts render as callouts, and YAML frontmatter becomes typed properties.

You end up with a report naming everything that could not be carried across, so nothing is lost quietly.

Import your vault

On the welcome screen, click Import.
Drag your vault folder onto the drop zone. There is no separate vault importer to find: the same zone takes documents, archives and vaults, and works out which it was given. A .zip of the vault works too, and if you would rather click than drag, use Choose an Obsidian vault folder.
Set a project name and language, check the board, and press Import.

If you change nothing, every note becomes a note and your folder structure is preserved exactly. That is the safe default, and it is never wrong.

The board

Instead of a list of questions, you get a picture of the project you are about to create.

┌── Wiki ────────────┐ ┌── Manuscript ──────┐ ┌── Entities ────────┐
│ ▸ Assets        4  │ │ ▾ Manuscript  ACT  │ │ Character      142 │
│ ▸ Events        61 │ │   ▾ Act One   CHAP │ │ Location        38 │
│ ▸ people       142 │ │     Ch. Two   SCENE│ │ Event           61 │
│   Index.md         │ │     Ch. Three SCENE│ │                    │
└────────────────────┘ └────────────────────┘ └────────────────────┘
  1,842 notes · 142 Character · 38 Location · 61 Event · 47 folders

Wiki and Manuscript are the two places a file can be. Everything starts in Wiki. Drag a folder — or a single note — into Manuscript and it becomes prose; drag it back and it is a note again. Every row also has a … menu with the same moves, which is usually quicker than dragging.

Entities is not a third place. It is a label over the Wiki tree: a grouped note is still created in the folder it came from, and hovering a group highlights its notes where they actually are.

The strip along the bottom is the whole import in numbers, and it updates as you move things. Nothing is written until you press Import.

Your prose

A folder dropped into Manuscript becomes an Act. Its subfolders become Chapters, and theirs become Scenes — so the structure you already built in your vault is the structure you get in the sidebar. Each file is then split into sections at its headings.

Four levels is the ceiling. A folder deeper than that gets no section of its own; its files are placed in the nearest Scene, and the report names every folder this happened to.

Sibling order follows your folder and file names. You can rearrange it in the sidebar once the project exists.

Use Manuscript only for folders that really hold prose — a wiki page split at its headings reads as a book that is not one. Page links, callouts and tags all survive the move, so a note that turns out to belong in the manuscript loses nothing by being there.

Characters, locations and events

If your vault uses frontmatter to say what a note is —

---
type: character
born: 1815-12-10
died: 1852-11-27
---

— those groups are already on the board when it opens. You declared them; you should not have to declare them again one dropdown at a time. type, class, category and kind are all recognised, and every value gets a group, however few notes carry it: a category you wrote down once is still a category.

A group becomes an entity type — records sharing a template, in the entity table, on the mindmap, and on a timeline.

Each card carries Fields, saying what each frontmatter key becomes: text, number, yes/no, choice, date, a tag, the start date or end date, or nothing at all. These are read from the group’s own notes, so a status that is draft/done across your characters becomes a choice with exactly those two options — not every value the word status has anywhere in your vault.

Rename a card by typing in it. Ungroup returns its notes to being ordinary notes. Drag a note onto another card to move it, or drag it off to take it out.

Where your vault says nothing, Scriptorium may offer a Suggested group of notes that share a shape. A suggestion claims nothing until you press Accept.

Getting this wrong is not destructive. Properties work on ordinary notes too, so a mistake costs the shared template and the timeline placement, not your data.

Anything you move to Manuscript leaves its group. Move it back and it rejoins — nothing is lost in between.

Dates

Two things worth knowing:

Ambiguous dates are refused, not guessed. 03/04/2024 is 3 April in most of the world and 4 March in the United States, and nothing in the file settles it. Scriptorium keeps the value as text and names the file and key in the report. Write 2024-03-04, 2024/03/04 or March 4, 2024 and it is read as a date.
Times do not move. A birthday written as 1885-03-12T10:30+02:00 imports as 12 March, 10:30. Time zones never shift a date.

Scriptorium fills the two timeline slots itself when it recognises a pair — born/died, birth/death, start/end, from/to — so a character with born and died lands on the timeline as a span without your doing anything.

The timeline has one start and one end, so at most one start date and one end date key per group — handing the slot to a second field takes it off the first. Every date key still becomes a date field regardless, so a vault with born, died, crowned and modified can put born and died on the timeline and keep all four.

Leaving things out

Drag a folder or a note to Not imported and it is skipped entirely, along with everything under it. The bin only appears once something is in it.

What comes across

Structure

Obsidian	Scriptorium
Vault folder	A new project, under one folder named after your vault
Nested folders	The same nesting in the sidebar, and Act / Chapter / Scene in the manuscript
`.md` files	Notes, or entities and manuscript sections per the board
Images, PDFs, audio	File attachments

In the text

Obsidian	Scriptorium
Headings, lists, tables, code, task lists, $math$	The same
`> [!note] Title` callouts	Callouts, with the title as their first line
`==highlight==`	A highlight
`%%comment%%`	An annotation anchored to the passage it sat in
`#tag` and frontmatter `tags:`	Tags, nesting preserved
Frontmatter	Typed properties
`[^1]` footnotes	Real footnotes, with the definition’s text inside them

Links

Obsidian	Scriptorium
`[[Note]]`	A page link, and a backlink on the other end
`[[Note\|alias]]`	A page link reading “alias”
`![[image.png]]`	The image, stored in your project
`![[Note]]`	A link card — Scriptorium has no transclusion
`[[Note#Heading]]`	A link to the note; the heading is shown in the link text
`[[Ghost]]`	Plain text, listed in the report
`[Ada](People/Ada.md)`	A page link, same as the wikilink form
`![](Assets/map.png)`	The image, stored in your project

Both link styles work, so a vault with Use [[Wikilinks]] turned off imports with its links intact.

Links are resolved the way Obsidian resolves them, including shortest-unique basenames and frontmatter aliases. Where two files could have matched, the report says which one was chosen.

What does not come across

Canvases (.canvas) are counted and skipped.
Dataview and Templater blocks are imported verbatim as code. They will not evaluate.
Block references (^block-id) and heading anchors link to the note rather than to the exact block.
Callout fold state and inline HTML tags are dropped; the text inside them is kept.
A footnote with no definition anywhere in the file stays as the [^1] you wrote — there is nothing to put in it.

All of this is listed in the report at the end of the import, which you can copy to work through later.

Cancelling

A large vault takes a while — a few thousand notes is tens of seconds. The progress bar is accurate, and Cancel works at any point. Cancelling leaves nothing behind: no half-built project appears on your shelf.