Mldoc

Another Org-mode and Markdown parser implemented using OCaml and Angstrom. It’s based on mlorg which is a high quality Org-mode parser written by Simon Castellan.

Who’s using Mldoc?

• Logseq, a local-first notes app (In development)

Build

The OCaml library remains named mldoc, with the same public modules and parsing/export interfaces. Tools are installed through separate opam packages:

Package	Purpose and installed artifacts
mldoc	OCaml library; no CLI, JS toolchain, or Core benchmark dependencies
mldoc-cli	Native mldoc command; adds Cmdliner and Lwt
mldoc-js	$(opam var mldoc-js:share)/index.js; adds js_of_ocaml and its PPX
mldoc-bench	mldoc-bench, mldoc-time-parse, mldoc-time-graph; adds Core packages

Companion packages require the matching version of the core library. Core keeps the Angstrom lookahead/continuation fork and Xmlm attribute-newline fork, both pinned to commits. Only the benchmark package is unavailable on Windows because it depends on Jane Street’s native benchmark tools.

# default: build only the library
make

# independently build optional targets
make cli
make js
make bench

# all targets (includes native benchmarks)
make all

# existing library regression tests
make test

# install the library from this checkout
opam install ./mldoc.opam

# register this checkout's core, then install one matching companion
opam pin add -yn --kind=path mldoc .
opam install ./mldoc-cli.opam
# or: ./mldoc-js.opam / ./mldoc-bench.opam

Use an explicit manifest for a single package. opam install . selects all packages in the checkout. Make’s optional targets build the local core and selected tool together; a companion’s opam build uses the installed library.

The JS opam package provides the existing Mldoc JavaScript export; it does not install the npm command wrapper. The npm package and its Node CLI remain available as before. deploy-npm-package builds only the JS target.

Installed benchmarks include their example inputs. Run fixture-generating timing tools in a writable scratch directory, and pass an explicit synthetic or intended graph directory to mldoc-time-graph:

bench_dir=$(mktemp -d)
cp -R "$(opam var mldoc-bench:share)/examples" "$bench_dir/"
cd "$bench_dir"
mldoc-bench -help
mldoc-time-parse
mldoc-time-graph /path/to/benchmark-fixture

Run utop

cd lib
dune utop

Usage

For Javascript users

# install mldoc
npm install -g mldoc

# convert org mode file to html
mldoc convert -i ./test.org -o ./test.html

# convert markdown mode file to html
mldoc convert -i ./test.markdown -o ./test.html

For OCaml users

# compile the native CLI
make cli

# convert org file to html
_build/default/bin/main.exe ./test.org -o ./test.html

Invoke utop in Emacs

opam config exec -- dune utop lib -- -emacs

Parsing todos [12/12]

Heading [7/7]

1. [X] level
2. [X] marker
3. [X] priority
4. [X] title
5. [X] tags
6. [X] stats
7. [X] footnote

Markup (Inline) [14/14]

1. [X] Latex fragment
2. [X] timestamp
3. [X] entity
4. [X] macro
5. [X] statistics cookie
6. [X] footnote reference
7. [X] link
8. [X] direct link
9. [X] target
10. [X] verbatim
11. [X] code
12. [X] nested emphasis [4/4]
    1. [X] bold
    2. [X] underline
    3. [X] italic
    4. [X] strike_through
13. [X] subscript
14. [X] superscript

Table [2/2]

1. [X] preliminary support
2. [X] column groups

List [3/3]

1. [X] Unordered list
2. [X] Ordered list
3. [X] Definition list

Directive

Block [5/5]

1. [X] src
2. [X] quote
3. [X] example
4. [X] custom
5. [X] block nested in block

Comment

Drawer

Not exported.

Horizontal

Latex environment

Quoting

TOC

Export [2/2]

1. [X] json
2. [X] html