https://github.com/sercxanto/logseq_to_obsidian
Yet another Logseq to Obsidian converter
https://github.com/sercxanto/logseq_to_obsidian
logseq markdown obsidian python
Last synced: 16 days ago
JSON representation
Yet another Logseq to Obsidian converter
- Host: GitHub
- URL: https://github.com/sercxanto/logseq_to_obsidian
- Owner: sercxanto
- License: mit
- Created: 2025-10-04T14:43:37.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-25T12:23:46.000Z (20 days ago)
- Last Synced: 2026-01-26T03:30:32.566Z (19 days ago)
- Topics: logseq, markdown, obsidian, python
- Language: Python
- Homepage:
- Size: 259 KB
- Stars: 14
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Logseq → Obsidian Converter
[](https://codecov.io/gh/sercxanto/logseq_to_obsidian)
## Overview
- Converts a Logseq vault (Markdown flavor) to Obsidian-friendly Markdown.
- Handles page properties → YAML front matter, task statuses, block IDs, and block references.
- 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: ` → Emoji: `⏳ YYYY-MM-DD[ HH:MM]`; Dataview: `[scheduled::YYYY-MM-DD[ HH:MM]]`
- `DEADLINE: ` → Emoji: `📅 YYYY-MM-DD[ HH:MM]`; Dataview: `[due::YYYY-MM-DD[ HH:MM]]`
- Repeaters: `. +N` or `++N` → “every N when done”; `+N` → “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:: ` lines are converted to Obsidian block anchors by appending `^` to the owning block line.
- Block references:
- `(())` → `[[#^]]` (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 (())}}` → `![[#^]]`
- `{{embed [[Some Page]]}}` → `![[Some Page]]`
- Images in assets:
- `` or `` → `![[image.png]]` (alt text is not preserved)
- With size attributes: `{:height H, :width W}` → `![[image.png|WxH]]` (width × height)
- 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 `: 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 `: 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.
- Complex block property drawers beyond `id::` are not transformed (left in place).
- Skips Logseq's internal `logseq/` metadata folder.
- 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](https://help.obsidian.md/create-note)
- 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](CONTRIBUTING.md)