Skip to content
Colletta docs

Import markdown and Obsidian vaults

If your notes already live in markdown files, you can import them. Colletta imports a zip of markdown files, including an Obsidian vault or a zip downloaded from Colletta, and turns each supported file into a document. Links between the files are converted and images are uploaded along with them. The preview shows what will be converted, files it can’t import and links that won’t resolve, before you start.

Anyone who can edit can import into any folder they can add to.

Start an import

Section titled “Start an import”

Zip the folder first. Most computers can do this from the folder’s right-click menu. Then open the Import screen in one of three ways:

  • Import in the + menu beside Documents in the sidebar.
  • Import here… in a folder’s menu, to put the import inside that folder.
  • Import a zip on the General settings page (Owners and Admins).

Choose, check, then import

Section titled “Choose, check, then import”
  1. Choose the zip and where to put it: the top level or a folder. Imported documents are published, so everyone who can open that folder can open them. Turn on Keep as drafts to make them your drafts instead.
  2. Check the preview. Before anything is created, Colletta reads the zip and shows what it will make: the folder name and how many documents, folders and images. Under Check before importing it lists anything worth a look, such as links that won’t resolve, files that aren’t markdown, or images it can’t upload.
  3. Import. A progress bar shows how far along it is. You can leave the page while it runs, or choose Cancel import to stop.
  4. Read the report. It says what was made and lists anything left out. Show the folder in the sidebar takes you to the new folder.

Your recent imports, at the bottom of the Import screen, keeps your last 20 imports, each with its report.

Where your files go

Section titled “Where your files go”

Each import makes one new folder, named after the zip or vault, inside the folder you chose. Your folders and files keep their structure inside it. Nothing already in the workspace is changed.

To undo an import, delete that folder. Deleting needs Full access, and the folder goes to the trash like any other.

The new folder has the same access as the folder it’s in. Imported documents are published unless you turned on Keep as drafts; drafts stay private to you and the co-authors you invite.

What’s converted

Section titled “What’s converted”
  • Markdown files (.md and .markdown) become documents, titled from their file names.
  • Links between files, such as [the plan](../Plan.md#risks), become links between the new documents, headings included. Links to sites on the web stay as they are.
  • Obsidian wikilinks: [[Note]], [[Note|other words]] and [[Note#Heading]] become document links, found the way Obsidian finds them. A link to a note that isn’t in the zip stays as plain text and is listed in the report.
  • Obsidian embeds: an embedded image such as ![[photo.png|300]] becomes an uploaded image, at that width. An embedded note, ![[Note]], becomes a link to it.
  • Obsidian callouts become the five callout types Colletta shows, the closest match for each, with any title as a bold first line.
  • Images (PNG, JPEG, GIF and WebP up to 10 MB) are uploaded once, even if several documents use them, with their location and camera details removed as usual. A still image over the plan’s per-image limit is made smaller to fit where possible, but GIFs and animations must already fit. The preview and the report list images that can’t be imported. Images count toward the workspace’s image storage.
  • Front matter, tags, code and HTML are kept exactly as written.

Mentions in imported text don’t notify anyone. A mention someone types later works as usual.

What’s left out

Section titled “What’s left out”
  • Other files, such as PDFs, audio and video, and images that no document uses. The report lists them.
  • Obsidian’s settings (the .obsidian folder), its trash, .git folders and hidden files. These are skipped quietly.
  • Empty folders.
  • Files over 4 MB, or with more than 1,000,000 characters of text.

Limits

Section titled “Limits”

A zip can be up to 100 MB and hold up to 2,000 files. Folders in Colletta nest up to eight levels deep, counting the folders above the import, so documents in deeper folders go into the deepest folder allowed. The report says when that happens. You can run one import at a time.

Notion and Confluence exports aren’t supported yet. We plan to add them.