gitwtfhub

wtf is lsdoc?

martinkoutecky/lsdoc — explained in plain English

Analysis updated 2026-05-18

1RustAudience · developerLicenseSetup · moderate

TL;DR

A Rust parser that reads Logseq flavored Markdown and Org files and matches Logseq's own parser exactly, meant to replace inconsistent parsing code in a sibling note app.

Mindmap

mindmap
  root((lsdoc))
    What it does
      Parses Logseq markdown
      Parses Logseq Org
      Matches mldoc exactly
    Tech stack
      Rust
      Node.js
      Cargo
    Use cases
      Replace inconsistent parsers
      Build search indexes
      Fuzz test parsing
    Audience
      Rust developers
      Logseq tool builders

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Replace inconsistent, hand written Markdown or Org parsing code in a note taking app

REASON 2

Check how closely a custom parser matches Logseq's official mldoc parser on real notes

REASON 3

Build a search index or renderer for Logseq flavored Markdown and Org files

REASON 4

Fuzz test a text parser for crashes and slow performance on large inputs

What's in the stack?

RustNode.jsCargo

How it stacks up

martinkoutecky/lsdocabc3dz/mixxxabyo-software/ferro-stash
Stars111
LanguageRustRustRust
Setup difficultymoderatemoderatemoderate
Complexity2/54/5
Audiencedevelopergeneralops devops

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Node.js is enough to run the graph checker, building from source needs the Rust toolchain and a C compiler.

AGPL-3.0: you can use and modify the code, but if you run a modified version as a network service, you must share your source changes with its users.

Wtf does this do

lsdoc is a parser, written in Rust, for the special flavor of Markdown and Org text format used by the note taking app Logseq. A parser reads raw text and turns it into a structured, computer readable version of that text, called an AST, which other software can then use to render the page or build search indexes. This project is meant to behave exactly like Logseq's own official parser, called mldoc, for the parts that matter for search and rendering, so it can act as a drop in replacement. Its main intended use is inside a sibling project called Tine, a similar note taking app, which currently has two separate, inconsistent pieces of parsing code that this project is meant to replace with one shared, correct implementation. To prove it matches the real Logseq parser, the project runs both parsers side by side on the same input text and compares their output, a technique called differential testing. According to the README, this comparison currently passes on nearly 1,200 test inputs across both Markdown and Org formats, with zero differences, plus additional tests focused on individual blocks and inline text. It has also been fuzz tested, meaning it was fed large amounts of random input, over 160,000 times without crashing. Users who already use Logseq can check how lsdoc performs against their own notes: a small Node.js based tool clones the project, runs both parsers on the user's own Logseq folder, and writes a local comparison report, without uploading any of the user's notes anywhere. No Rust installation is needed for this check, since a ready built copy of lsdoc is downloaded automatically. The project is licensed under AGPL-3.0 and is consumed as a Rust dependency by other Rust projects.

Yoink these prompts

Prompt 1
Explain how lsdoc uses differential testing against mldoc to prove correctness
Prompt 2
Show me how to add lsdoc as a Rust dependency and call its parse and refs functions
Prompt 3
Walk me through running the graph-check tool against my own Logseq notes folder
Prompt 4
Explain what the normalized projection is and why spans are excluded from comparison
Prompt 5
Summarize the milestones lsdoc has completed toward full mldoc parity

Frequently asked questions

wtf is lsdoc?

A Rust parser that reads Logseq flavored Markdown and Org files and matches Logseq's own parser exactly, meant to replace inconsistent parsing code in a sibling note app.

What language is lsdoc written in?

Mainly Rust. The stack also includes Rust, Node.js, Cargo.

What license does lsdoc use?

AGPL-3.0: you can use and modify the code, but if you run a modified version as a network service, you must share your source changes with its users.

How hard is lsdoc to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is lsdoc for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.