Skip to content

Importing Markdown ​

There are three ways in, and they all end in the same place: real blocks, with headings, lists, tables, tasks and links intact.

Pasting ​

The quickest route for one page: paste Markdown into a page. The clipboard goes through the same parser export uses, so what you paste becomes blocks rather than a wall of text. Copying blocks back out gives you Markdown, from the same projection.

Importing a folder ​

For a whole vault, a docs directory or a Logseq graph: Import in the sidebar's foot, or Import Markdown or Logseq… in the command palette (⌘K / Ctrl K).

  1. Drop a folder on the dialog, or choose one. Images and attachments inside it come too.

  2. Read the preview. Nothing has been written yet. It tells you how many pages and journals the import will make, how many attachments it will upload, and anything worth a look before you go ahead:

    • journals for days that already exist, which the import will add to;
    • attachments a page refers to but that are not in the folder;
    • links that match no page, which stay as the text they were;
    • properties that had to be flattened, and syntax kept as text.

    The format is detected from the folder — logseq/config.edn, or pages/ beside journals/, means a Logseq graph — and you can change it.

    Which day the writing belongs to is yours to choose, and the preview shows what each choice does before anything is written. See dating an import.

  3. Import. Pages are created, attachments uploaded to them, and then the content written. If an upload fails, the pages are still written, the file stays a path in the text, and Retry the rest uploads only what failed.

Everything goes under one new page, "Imported from …". Trashing that page removes the whole import from the tree, and restoring it brings it back.

The import is offered to people who can create pages at the top of the workspace, and not while you are offline.

From the command line ​

sh
pnpm import:md ~/notes/my-graph            # preview: prints the report, writes nothing
pnpm import:md ~/notes/my-graph --apply    # import, and print a link to it

It takes the same steps as the dialog. --format markdown|logseq overrides the detection and --parent <pageId> imports under an existing page. --date import|file|YYYY-MM-DD chooses which day the writing belongs to (see below). With --date file, --file-dates git|modified says where a file's date comes from when its frontmatter has none. The default is git inside a repository and modified outside one. NOTESFLOW_API points it at a server, NOTESFLOW_WORKSPACE at a workspace, and NOTESFLOW_COOKIE carries a session when the server requires sign-in.

What a Markdown folder becomes ​

  • Frontmatter becomes page properties. Keys that are not frontmatter-shaped — nested objects — are flattened, and the report names each one.
  • Folders become parent pages. A folder with an index.md, readme.md or _index.md uses it as its own page; a folder without one gets a page so the tree still has a node there.
  • [[wikilinks]] are resolved against everything in the import — by title, by filename or by path — and relative .md links are rewritten too. Targets that match nothing stay as text.
  • Titles come from frontmatter, then the first heading, then the filename.
  • A file named YYYY-MM-DD becomes the journal for that day.
  • Images and linked files are resolved relative to the page that uses them and uploaded as attachments. Folders a tool keeps for itself — .obsidian/, .git/, .trash/ — are skipped.

What a Logseq graph becomes ​

In LogseqIn Notesflow
journals/2024_01_15.mdthe journal for 15 January 2024
pages/projects___roadmap.md (or projects%2Froadmap.md)projects/roadmap, nested under a projects page
title::, alias::, tags:: and other page propertiesthe title, other names links can use, and page properties
every line a bulletbullets; a bullet holding only a heading becomes the heading
TODO, LATER · DOING, NOW · WAITINGan unchecked task · one being done · one waiting
DONE · CANCELEDa checked task · an unchecked task marked cancelled
SCHEDULED: <2024-01-20>the task's declared date
DEADLINE: <2024-01-20>the task's due date
a bullet that is only ((uuid)), or {{embed ((uuid))}}a block reference to that block
((uuid)) inside a sentencea link to the block's page, reading as the block's words
{{embed [[page]]}}a link to the page
#tag, #[[multi word]]a link, when a page by that name exists
[[page]] with no filea page is created for it, as Logseq has one
id::, collapsed::, :LOGBOOK:used or dropped — they describe the outliner, not the writing
other block properties, {{query}} and other macroskept as text, and listed in the report
../assets/image.pngan uploaded attachment; Logseq's {:height …} sizing is dropped
logseq/, bak/, version-files/, whiteboards/not imported

Dating an import ​

Imported writing is always recorded as arriving now, by whoever ran the import. That is the log's own clock, and no choice below changes it. By default it is also the only day the writing belongs to: the timeline shows it under today.

You can choose differently. Your choice places the writing on another day as well, as its declared date. On the timeline it then appears under that day marked "Placed here", and under today as written.

ChoiceEach file's writing is also placed on
The day it is imported (default)nothing more
One date for all of itthe date you give
Each file's own dateits frontmatter date: (or created:), else a journal's own day, else the day the file was first committed to git (command line, inside a repository) or last modified

A file that has no date from any of these stays under today only. So does a block that already carries its own date, such as a Logseq SCHEDULED: task. On the timeline, one page placed on a day reads as one row ("lead placed 38 blocks of ADR 0003"), which opens to show every block.

A modification time is often not what you want: a folder copied or cloned today has today's modification times. For a repository, prefer the command line, which reads each file's first commit.

To undo a placement, clear the block's date, the same as any other placement.

What import does not do ​

It does not restore history. An imported page's blocks are recorded as created now, by whoever ran the import, because that is the truth: the log records when the block came into this workspace, and a file's date says something else. A date you choose places the writing on a day (above); it never rewrites when the writing was recorded.

The one exception runs the other way: a file Notesflow itself exported carries block ids in a sidecar, and merging it back keeps those blocks' identity and their authored dates. That works because the workspace already has the history; the file is only being reconciled against it.

Obsidian's ^block-ids and <!-- region --> markers are read as the blocks' names and regions. Not yet read on import: Obsidian's ![[embeds]], which are not embedded (one naming a whole page becomes a link to it, after its !), and [[page#heading]] links, which stay as the text they were and are reported as links that matched no page; Logseq whiteboards; and Logseq's newer database graphs, which are not Markdown at all.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.