GitHub - andreoliwa/logseq-doctor: Heal your Markdown files: convert to outline, list tasks and more tools to come · GitHub

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

andreoliwa

/

logseq-doctor

Public

Uh oh!

There was an error while loading. Please reload this page.

Notifications
You must be signed in to change notification settings

Fork
7

Star
82

Code

Issues
10

Pull requests
6

Discussions

Actions

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Discussions

Actions

Security and quality

Insights

andreoliwa/logseq-doctor

 masterBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History757 Commits757 Commits.github.github  cici  cmdcmd  docsdocs  internalinternal  pkg/setpkg/set  src/logseq_doctorsrc/logseq_doctor  teststests  .codeclimate.yml.codeclimate.yml  .cookiecutterrc.cookiecutterrc  .coveragerc.coveragerc  .cruft.json.cruft.json  .cz.toml.cz.toml  .editorconfig.editorconfig  .env.tests.env.tests  .gitignore.gitignore  .golangci.yaml.golangci.yaml  .gomarkdoc.yml.gomarkdoc.yml  .goreleaser.yaml.goreleaser.yaml  .pre-commit-config.yaml.pre-commit-config.yaml  .pre-commit-hooks.yaml.pre-commit-hooks.yaml  .prettierignore.prettierignore  .prettierrc.toml.prettierrc.toml  .releaserc.json.releaserc.json  .tool-versions.tool-versions  LICENSELICENSE  MakefileMakefile  go.modgo.mod  go.sumgo.sum  mkdocs.ymlmkdocs.yml  pyproject.tomlpyproject.toml  tox.initox.ini  uv.lockuv.lock  View all filesRepository files navigationREADMEContributingMIT licenseLogseq Doctor

Logseq Doctor: heal your flat old Markdown files before importing them to Logseq.
📚 Read the full documentation
NoteThis project is still alpha, so it's very rough on the edges
(documentation and feature-wise).
At the moment, it has both a Python and Go CLI.
The long-term plan is to convert it to Go and slowly remove Python.
New features will be added to the Go CLI only.

What is Logseq Doctor?
Logseq Doctor is a command-line tool with commands to manipulate your Logseq Markdown files. It provides utilities to:

Convert flat Markdown to Logseq's outline format
Append content to pages and journals
Create task backlogs that are easily viewed and prioritized in the mobile app
Manage tasks in Logseq
Clean up and tidy Markdown files
Prevent invalid content to be committed
And more stuff to come...

Features

Backlog Management (backlog): Aggregate tasks from multiple pages into unified backlogs with smart categorization, overdue detection, and focus page generation
Content Management (content): Append raw Markdown content to Logseq pages or journals
Markdown Integration (md): Parse and add Markdown content using DOM manipulation with support for parent blocks and journal targeting
Task Management (task add): Add new tasks or update existing ones with key-based search, preserving children and properties
Tidy Up (tidy-up): Clean up and standardize your Markdown files
Fast Performance: Written in Go for speed and efficiency
Outline Conversion (outline): Convert flat Markdown files to Logseq's outline format
Task Listing (tasks): List and manage tasks in your Logseq graph

Installation
Go binary executable
The recommended way for macOS and Linux is to install with Homebrew:
brew install andreoliwa/formulae/logseq-doctor

Or you can install manually:
go install github.com/andreoliwa/logseq-doctor/cmd/lqd@latest

Confirm if it's in your path:
which lqd
# or
ls -l $(go env GOPATH)/bin/lqd

Python executable
The recommended way is to install logseq-doctor globally with
pipx:
pipx install logseq-doctor

You can also install the development version with:
pipx install git+https://github.com/andreoliwa/logseq-doctor

You will then have the lqdpy command available globally in your system.
Build from source
To build and install from the source (both Python and Go executables), clone the repository and run:
make install

Quick start
Type lqd (the Go executable) without arguments to check the current commands and options:
Logseq Doctor heals your Markdown files for Logseq.

Convert flat Markdown to Logseq outline, clean up Markdown,
prevent invalid content, and more stuff to come.

"lqdpy" is the CLI tool originally written in Python; "lqd" is the Go version.
The intention is to slowly convert everything to Go.

Usage:
lqd [command]

Available Commands:
backlog Aggregate tasks from multiple pages into a unified backlog
completion Generate the autocompletion script for the specified shell
content Append raw Markdown content to Logseq
help Help about any command
md Add Markdown content to Logseq using the DOM
task Manage tasks in Logseq (subcommands: add)
tidy-up Tidy up your Markdown files

Flags:
-h, --help help for lqd

Use "lqd [command] --help" for more information about a command.

Type lqdpy without arguments to check the current commands and options:
Usage: lqdpy [OPTIONS] COMMAND [ARGS]...

Logseq Doctor: heal your flat old Markdown files before importing them.

Options:
-g, --graph DIRECTORY Logseq graph [env var: LOGSEQ_GRAPH_PATH;
required]
--install-completion [bash|zsh|fish|powershell|pwsh]
Install completion for the specified shell.
--show-completion [bash|zsh|fish|powershell|pwsh]
Show completion for the specified shell, to
copy it or customize the installation.
--help Show this message and exit.

Commands:
outline Convert flat Markdown to outline.
tasks List tasks in Logseq.

Development
To set up local development:
make setup

Run this to see help on all available targets:
make

To run all the tests run:
tox

Note, to combine the coverage data from all the tox environments run:

OS

Windows
set PYTEST_ADDOPTS=--cov-append tox

Other
PYTEST_ADDOPTS=--cov-append tox

About

Heal your Markdown files: convert to outline, list tasks and more tools to come

andreoliwa.github.io/logseq-doctor/

Topics

python

markdown

python3

knowledge-graph

knowledge-base

markdown-format

markdown-formatter

logseq

markdown-formatting

logseq-plugin

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

82
stars
Watchers

2
watching
Forks

7
forks

Report repository

Releases
10

v0.7.0

Latest

Nov 1, 2025

+ 9 releases

Sponsor this project

Uh oh!

There was an error while loading. Please reload this page.

ko-fi.com/andreoliwa

liberapay.com/andreoliwa

https://www.paypal.me/andreoliwa

https://www.buymeacoffee.com/andreoliwa

Learn more about GitHub Sponsors

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Go
72.8%

HTML
14.6%

Python
8.4%

CSS
3.5%

Makefile
0.7%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

Logseq Doctor is a command-line tool designed to manage and heal flat Markdown files specifically to prepare them for import into Logseq. The primary objective of the project is to provide utilities that address common issues found in existing Markdown files, focusing on Markdown formatting and task management to ensure data integrity before integration into the Logseq environment. The tool currently features both a Python and a Go command-line interface, with a stated long-term goal of transitioning the entire tool to the Go implementation and phasing out the Python components.

The feature set of Logseq Doctor encompasses several critical areas of Markdown and Logseq workflow. Backlog management is a key capability, allowing users to aggregate tasks from disparate pages into unified backlogs, incorporating intelligent categorization, overdue detection, and the generation of focus pages to aid prioritization. Content management involves the ability to append raw Markdown content directly to Logseq pages or journals. Furthermore, the tool integrates with Markdown parsing by using DOM manipulation to accurately parse and add Markdown content, supporting features such as parent block tracking and journal targeting. Task management is handled through functions that allow users to add new tasks or modify existing ones using key-based searching, ensuring that hierarchical relationships and properties are preserved. A separate function exists to tidy up Markdown files by cleaning them up and standardizing the file structure. Additionally, the tool provides essential utilities for conversion, specifically converting flat Markdown files into the required Logseq outline format, and listing and managing the tasks within the Logseq graph structure.

From a technical standpoint, the tool emphasizes performance and efficiency, as it is implemented in Go, which contributes to its speed and operational efficiency. The command-line interface provides several distinct commands that facilitate these operations. For general execution, the Go binary executable, named lqd, is available for use. The Python executable, lqdpy, was the original command-line tool, and both versions exist to provide flexibility, with the intention of favoring the Go implementation. Specific commands available include backlog, completion, content, md, task, and tidy-up, each addressing a specific aspect of file and task manipulation. The development structure includes options for installing completion scripts for various shells and hooks for local development setup. The repository base relies on a license from the MIT license, and the project is actively maintained with a history of numerous commits and an existing user base indicated by its star count.