logseq-to-obsidian 0.2.0

Convert a Logseq vault to Obsidian-friendly Markdown

Logseq → Obsidian Converter

Overview

• Converts a Logseq vault (Markdown flavor) to Obsidian-friendly Markdown.
• Handles page properties → YAML front matter, task statuses, block IDs, block references, org-mode blocks → callouts, highlights, numbered lists, and more.
• Preserves non-page folders; moves pages/ content to the vault root.

Features

• Page properties (key:: value) at top → YAML front matter.
• Special mappings:
  • alias:: or aliases:: → aliases: [] (array)
  • tags:: → tags: [] (array, without #)
  • title:: → omitted (Obsidian only uses the filename as the note name). If the Logseq title mismatches the vault-relative output path, a warning is emitted so you can tidy it up.
• Task markers:
  • Recognized at the start of a list item (- STATE ..., uppercase only):
    • TODO, DOING, LATER, NOW, WAIT, WAITING, IN-PROGRESS → - [ ] ...
    • DONE, CANCELED, CANCELLED → - [x] ...
  • Priorities right after state ([#A|#B|#C]):
    • Emoji: A→⏫, B→🔼, C→🔽 (appended at end)
    • Dataview: [priority::high|medium|low] (appended at end; omitted if none)
  • Dates anywhere after the state:
    • SCHEDULED: <YYYY-MM-DD [Dow] [HH:MM] [repeater]> → Emoji: ⏳ YYYY-MM-DD[ HH:MM]; Dataview: [scheduled::YYYY-MM-DD[ HH:MM]]
    • DEADLINE: <YYYY-MM-DD [Dow] [HH:MM] [repeater]> → Emoji: 📅 YYYY-MM-DD[ HH:MM]; Dataview: [due::YYYY-MM-DD[ HH:MM]]
    • Repeaters: . +N<u> or ++N<u> → “every N when done”; +N<u> → “every N ”
    • Units: y=year(s), m=month(s), w=week(s), d=day(s), h=hour(s); pluralized when N ≠ 1
    • Ordering: append priority, then scheduled, then due, then repeat; block anchors (e.g., ^id) remain last
• Block IDs:
  • id:: <uuid> lines are converted to Obsidian block anchors by appending ^<uuid> to the owning block line.
• Block references:
  • ((<uuid>)) → [[<FileName>#^<uuid>]] (resolved by scanning all files first).
  • Optional: convert configured wikilinks [[key/value]] to Dataview inline fields [key::value] (non-embed, no alias, not inside code blocks).
• Alias links:
  • [Display Name]([[Page Name]]) → [[Page Name|Display Name]] (outside fenced code blocks).
• Embeds:
  • {{embed ((<uuid>))}} → ![[<FileName>#^<uuid>]]
  • {{embed [[Some Page]]}} → ![[Some Page]]
  • {{video https://...}} → ![](https://...)
  • {{youtube https://...}} → ![](https://...)
  • {{tweet https://...}} → ![](https://...)
• Images in assets:
  • ![alt](../assets/image.png) or ![alt](assets/image.png) → ![[image.png]] (alt text is not preserved)
  • With size attributes: ![alt](../assets/image.png){:height H, :width W} → ![[image.png|WxH]] (width × height)
• Org-mode blocks:
  • #+BEGIN_QUOTE ... #+END_QUOTE → > blockquote lines.
  • #+BEGIN_NOTE, #+BEGIN_TIP, #+BEGIN_WARNING, #+BEGIN_IMPORTANT, #+BEGIN_CAUTION, #+BEGIN_EXAMPLE → Obsidian > [!type] callouts. The first bold line inside the block becomes the callout title.
  • #+BEGIN_COMMENT ... #+END_COMMENT → %% ... %% (Obsidian hidden comments).
  • Other admonition-like block types (CENTER, VERSE, PINNED) fall back to > [!note].
  • Unknown block types (e.g. #+BEGIN_SRC, #+BEGIN_QUERY) are left unchanged, so code and query content is preserved verbatim.
  • Nested blocks are supported (e.g., a quote inside a callout produces nested > > ...).
  • Blocks inside indented list items preserve their indentation in output.
  • This handles org-style block syntax embedded in Logseq's Markdown files; it does not add support for Logseq vaults stored in Org format (.org files).
• Highlights:
  • ^^text^^ → ==text== (Obsidian highlight syntax). Skipped inside fenced code blocks.
• Numbered lists:
  • Logseq stores numbered lists as regular bullets with a hidden logseq.order-list-type:: number property. These are converted to standard Markdown numbered lists (1., 2., 3....) with correct sequential numbering that resets across indent levels and non-numbered items.
• Task date properties:
  • created:: [[YYYY-MM-DD]] or created:: YYYY-MM-DD → appends ➕ YYYY-MM-DD
  • completed:: ... or done:: ... → appends ✅ YYYY-MM-DD
  • cancelled:: ... or canceled:: ... → appends ❌ YYYY-MM-DD
  • Works with or without a leading dot (e.g., .created::) and with or without [[]] around the date.
• Logseq metadata cleanup:
  • :LOGBOOK: ... :END: time-tracker blocks are removed.
  • Remaining logseq.* namespaced block properties (e.g., logseq.toc::) are removed.
• Headings followed by indented lists:
  • If a heading line is immediately followed by an indented list (≥4 spaces or tabs), prefix the heading with - (i.e., - # Heading).
  • Rationale: Logseq treats such lists as children of the heading; Obsidian otherwise renders them as quoted/code blocks. This keeps folding behavior aligned.
• Journals:
  • Renames YYYY_MM_DD.md → YYYY-MM-DD.md and can move journals to a specific folder.
• Assets and other files are copied as-is.

Installation

• pipx (recommended): pipx install logseq-to-obsidian
• pip: pip install logseq-to-obsidian
• From Git (development version): pipx install "git+https://github.com/sercxanto/logseq_to_obsidian.git@main"

Usage

logseq-to-obsidian \
  --input /path/to/logseq-vault \
  --output /path/to/obsidian-vault \
  --daily-folder "Daily Notes" \
  --tasks-format emoji \
  --field-key project \
  --field-key topic \
  --dry-run

Alternatively (no console script), you can run:

python -m logseq_to_obsidian \
  --input /path/to/logseq-vault \
  --output /path/to/obsidian-vault \
  --dry-run

Options

• --input: Path to the Logseq vault root (folder containing pages/, journals/, etc.).
• --output: Destination Obsidian vault directory (created if not exists).
• --daily-folder <name>: Move journals/ into this folder in the output. If omitted, keeps journals/.
• --tasks-format {emoji|dataview}: Choose output format for Tasks metadata (priorities now; dates later). Default: emoji.
• --field-key <key>: Convert wikilinks of the form [[key/value]] to Dataview inline fields [key::value]. Repeatable for multiple keys.
• Pages are always flattened to the vault root; see "File placement rules" below.
• --dry-run: Print planned changes without writing files.

Notes and assumptions

• Only Markdown (.md) files are transformed; other files are copied.
• Block reference resolution requires that id:: appears for referenced blocks in the source files.
• This tool is conservative: it preserves unknown page properties in YAML.
• Block-level collapsed:: properties are ignored; Obsidian stores list collapse state outside Markdown.

Limitations

• Does not parse or migrate the Logseq database; operates purely on Markdown files.
• Skips Logseq's internal logseq/ metadata folder.
• Skips a top-level .git/ directory if present.
• Skips Logseq whiteboards (whiteboards/); a warning is emitted since Obsidian cannot read Logseq's whiteboard format.
  • Only normalizes heading + indented list patterns outside fenced code blocks; headings already inside list items are left unchanged.
• Logseq percent-encodes invalid characters in filenames; this tool preserves those filenames and emits a warning when detected. It does not attempt to decode them to avoid invalid output names or collisions, so you may need to rename notes in Logseq first if Obsidian links are broken.
• Please make sure that the Logdeq's file name format is triple-lowbar, see the documentation
• File times are preserved: output files keep the original source modification time (mtime) for both transformed Markdown and copied assets.

File placement rules

• Pages: All files from Logseq's pages/ are placed at the root of the Obsidian vault.
• Nested paths: Logseq encodes subfolders in page filenames using three underscores ___.
  • Example: pages/a___b.md becomes a/b.md.

Journals

• Journal filenames are always renamed from YYYY_MM_DD.md to YYYY-MM-DD.md.
• Logseq already displays journal page links using dashes (e.g., [[2024-08-30]]), so link text does not need conversion.

Development / Contributing

See CONTRIBUTING.md