Importing A Knowledge Base · EtherPK User Docs

Import brings an existing folder of notes, or a zip of one, in as a new knowledge graph. The source is only ever read - your original graph or vault stays exactly as it was.

An import always creates a new graph. It cannot add documents to an existing graph, and it does not convert the source folder in place. Moving a local graph into synced storage therefore leaves the local graph untouched and creates a separate synced graph.

Supported sources

Source	Detected by	Notes
Logseq	A `logseq/` directory in the folder	Namespaces, task markers and journal names are converted
Obsidian	A `.obsidian/` directory	Folder clashes, piped links and the Tasks plugin's emoji are converted
EtherPK	The `journals/`, `pages/`, `assets/` layout	A local graph's folder, a Local Mirror or an export zip - the way to rebuild a synced graph from its copy, or move one to another account
Plain markdown	Anything else	A folder of `.md` files
AS Notes	A `.asnotes/` folder, in the folder you pick or one folder down	Journals, tasks and nested wikilinks come across as they are. Kanban boards become task lists, and encrypted notes are left out. See AS Notes workspaces below

Import a folder or a zip

On the Graphs page, select Import.
Choose the source folder, or Choose a zip… for a zipped one: an export from Settings > Mirror and Export, or a vault zipped by any tool. Either is read once and never written to. A zip with a single top-level folder is read as that folder, and a large zip is read piece by piece rather than loaded whole.
Check the detected format (you can override it), give the graph a name, and choose where it is stored:
- Local folder: plain markdown files in a new, empty folder you choose. Needs a Chromium-based desktop browser. If the folder you pick is not empty the import refuses - it never adopts or overwrites an existing folder.
- Synced graph: end-to-end encrypted on your Sync Server, available on every device. There is no destination folder, because EtherPK creates a new graph on the server. When an EtherPK source has protected documents, the dialog also asks for their Protection passphrase. A synced graph gives every image and file a new name, and the names inside a protected document can only be updated with its passphrase. Without it the documents still arrive and open with the passphrase as usual, but images inside them do not display.
Select Import. The window closes and the import carries on in the corner as an activity.

Only one import runs in a browser tab at a time. You can close the window, open another graph and keep working while it reports progress.

Before importing into a synced graph

Synced graph is offered only after this device is connected to a Sync Server and the server has confirmed your account. Connect on the Sync tab of the Knowledge graphs page first (Synced Graphs). With more than one Sync Server connected, Sync Server under Synced graph chooses which one the graph goes to, and a server that cannot take it now says why.

If your account already has Encryption Keys and they are locked on this device, the import asks you to unlock them before it starts: with this device's passcode if it has one (Device Passcode), otherwise by approving from a device that is unlocked or entering your Recovery Code. Nothing is created on the server until the Encryption Keys are in hand, and cancelling the prompt cancels the import.

If this is your account's first synced graph, EtherPK creates your Encryption Keys first and shows you the Recovery Code. Save it and confirm, and the import begins - nothing is uploaded before that. The order is deliberate: the graph's content is encrypted under a Graph Key kept with your other Encryption Keys, and until the server stores them sealed, anything already uploaded could not be opened again. See Recovery Code And Device Approval.

While it runs and when it ends

For a synced destination, EtherPK converts the source, encrypts and uploads its assets, prepares the documents, then waits for the server to confirm the encrypted changes. The graph joins this device's graph list only when the import has reached its final step.

Imported means the server has confirmed every document. Select Open on the activity to enter the graph - EtherPK does not move you there on its own.
Still syncing to the server means the encrypted work is safe in this browser's cache but the server has not yet confirmed every document. Open the graph to resume delivery.
A failure or a cancellation removes the destination graph rather than leaving a half-imported one in your list: the graph, every document already pushed and every asset chunk already stored are all removed.
Leaving the page while an import runs asks you to confirm first. If the tab is closed or reloaded anyway, the import stops partway, and the Graphs page lists it under Imports that did not finish the next time it opens in this browser. For a synced import, Delete the partial graph removes what it uploaded, and the graph is marked Import interrupted until you decide. For a folder import, the page names the folder that holds the partial graph, which must be emptied before importing into it again.

What is converted

Documents, assets, journals and links all come across.

Tasks become markdown checkboxes with task tags: priorities map to #P1, #P2 and #P3, waiting to #W, deadlines to #D-2026-03-20 style dates. Logseq's TODO, DOING and DONE markers and the Obsidian Tasks plugin's emoji are both understood. See Tasks.
Journals are named by their ISO date (2026-07-16.md), and links to journal pages such as [[Jul 16th, 2026]] are rewritten to match.
Logseq namespaces (physics/quantum) and Obsidian folder clashes become scoped concepts, [[[[physics]] quantum]]. See Scoped Concepts.
Piped links ([[Target|label]]) keep the label when it is the target or one of its aliases - otherwise the label stays in the prose with the link beside it.
Frontmatter comes across with every property. In a synced graph the title: line leaves the block, because the graph keeps each document's name. aliases: stays, so the page shows every name it answers to. See Titles Aliases And Frontmatter. A block that is not valid YAML is kept exactly as written, and the Import Report names the page. EtherPK reads none of its properties until you correct it.
Obsidian aliases in older forms become an aliases: list: text split at its commas (aliases: AI, Artificial Intelligence) and the singular alias key. Obsidian deprecated both in version 1.4, and vaults saved by older versions still hold them.
Obsidian comments (%% … %%) are removed. Obsidian hides them, but EtherPK would show them and publish them, so the Import Report lists each one with its text instead.
Obsidian callouts (> [!note] Title) become quotes that open with the type and title in bold: > **Note: Title**. The quote's own lines are unchanged.
Footnotes, tags and canvases stay as written, and the Import Report names each note that has them: EtherPK does not render footnotes or treat #tag as a tag, and a .canvas file arrives as a file with no view of its own.
Highlights written the older Logseq way, ^^text^^, become ==text==.
Indentation is put on EtherPK's two-space grid: a four-space vault or a tab-indented page lands nested exactly as it was, with the deeper lines of each bullet moved by the same amount.
Images are copied as they are. An import never optimises them, so a vault of screenshots arrives at full size.
Constructs with no EtherPK equivalent (embeds, block references, queries) degrade to the nearest readable markdown. Nothing is silently deleted.
Protected documents in an EtherPK source are carried through unchanged and named in the report. A local graph's folder, a mirror and an export all carry the protection record beside them, and the new graph adopts it, so the same passphrase opens them there. A source without the record leaves them encrypted under a key the new graph does not have. Into a synced graph, enter the passphrase when the dialog asks, so the images and files inside them come across too. See Protected Documents.
An EtherPK folder's AGENTS.md and CLAUDE.md are not imported as pages. They belong to the folder they came from - a local destination graph writes its own the first time it opens.

AS Notes workspaces

AS Notes and EtherPK write journals, tasks and wikilinks the same way, so most notes come across unchanged. The differences are in folders, titles and the files AS Notes keeps for its own features.

The notes folder is the folder that holds .asnotes/. When AS Notes was set up in a folder inside the one you pick (its as-notes.rootDirectory setting), only that folder is imported. The journal and template folders are read from the workspace's .vscode/settings.json when it is there.
Journals named the older AS Notes way, 2026_03_15.md, are renamed to 2026-03-15.md, and the links to them are updated.
Folders flatten, as they do for Obsidian. When notes in different folders share a name, each becomes a scoped concept, and every link points at the note AS Notes would have opened: the one in the linking note's folder, or else the nearest one.
Links with characters a file name cannot hold, such as [[Design/Ideas]], which AS Notes opens as Design_Ideas.md, are rewritten to the page's name, [[Design_Ideas]].
title: only sets the published title in AS Notes, but EtherPK uses it as the page's name. Each page is named after its file, as AS Notes links name it, and the Import Report lists every page whose title: was different.
Frontmatter that is not valid YAML, such as title: Plans: 2026, is read the way AS Notes reads it and written back as valid YAML.
Tasks written with a * bullet get a -, which EtherPK needs to read them as tasks. The Import Report also lists a task whose text starts with #D, #C or #S-, because EtherPK reads those as task tags where AS Notes reads them as text. See Tasks.
Kanban boards become one page per board, named like [[Website]] Kanban, with one task per card, so the cards appear on Website's Kanban board (Kanban Boards). The card's lane sets the task's status (To Do is open, Doing is #D, Done is checked), its priority and due date become task tags, and its description, entries and files are nested under the task. A lane with no matching status leaves its cards open, and the Import Report names it.
Templates, such as templates/Journal.md, become pages under a Templates scope, [[Templates]] Journal, because EtherPK has no templates.
Encrypted notes (.enc.md files) are not imported. EtherPK cannot open AS Notes encryption, because AS Notes keeps the passphrase in VS Code. The import dialog says how many there are before you start, and the Import Report names each one. To bring one across, decrypt it in AS Notes, rename it without .enc, and import again.
The publish setup (asnotes-publish.json, its layouts, includes and themes, and the site it generates) is not imported. To publish from EtherPK, set up a publication (Publishing Your Notes As A Website).
.asnotesignore is honoured for plain folder and file names, such as private/ or /scratch.md. A pattern with a wildcard or a ! is not applied, and the Import Report lists it.

The Import Report

Every conversion that could not be lossless is listed on an Import Report page created inside the new graph, with a link to each affected document. Two kinds of entry sit side by side:

Conversion losses, which the source expressed and EtherPK cannot, and would be identical on a re-run.
Storage refusals, where an asset could not be stored, usually because it is larger than the plan's per-asset allowance, which you may be able to act on.

Files that could not be uploaded are counted on their own and listed first. When the activity offers Retry uploads and the retry stores them, the report says so at its end.

If your connection drops during a synced import, the uploads wait for it to come back and carry on, rather than listing the files as not uploaded.

The report is an ordinary page. Read it, follow up anything that matters, then delete it.