zim-to-markdown
Command line converter between Zim wiki pages and Markdown. It handles single pages and whole notebooks in both directions.
Stack
Haskell with Cabal. Stack is not used.
Versioning
PVP, single-sourced from the zim-to-markdown.cabal file.
- Patch: fixes and minor refinements.
- Minor: new user-facing features or screens.
- Major 2: data model breaking changes.
- Major 1: major release milestones.
Features
- Converts a single page to standard output or to a file.
- Converts a whole notebook recursively, reconstructing its folder structure.
- Accepts the notebook directory or its
notebook.zim configuration file as input.
- Strips the leading Zim metadata header and normalizes heading levels into consecutive Markdown levels.
- Copies or links external images with
--images copy|symlink|relative, so images and attachments keep working.
- Collapses inline formatting without a Markdown counterpart into bold, italic or strikethrough with
--formatting html|bold|italic|strike.
- Resolves internal Zim links across the notebook.
- Converts Markdown back to Zim, including notebook structure.
- Supports headings, emphasis, lists, task lists, links, images, anchors, tables, blockquotes, horizontal rules, and code blocks.
- Keeps conversion pure and reports failures as data.
Links
Documentation
Installation
Install the published package from Hackage with:
cabal install zim-to-markdown
The executable is installed into the Cabal binary directory, usually ~/.cabal/bin, which must be on PATH.
Prebuilt binaries
Prebuilt Linux, macOS, and Windows binaries are attached to GitHub releases. The release workflow builds Linux x86_64 on Ubuntu 22.04 (glibc 2.35 or newer), macOS ARM64, and Windows x86_64 archives, plus a Debian package for Linux x86_64. Build from source for other Linux distributions.
On Debian and Ubuntu, install the .deb with:
sudo apt install ./zim-to-markdown_<version>_amd64.deb
Requirements
Building from source or installing with cabal install requires a Haskell toolchain. The project is tested with:
- GHC 9.6.7 and 9.14.1
- cabal-install 3.18.1.0
The release binaries use GHC 9.14.1.
On Debian and Ubuntu, install the libgmp-dev package before building, because GHC links against GMP.
The prebuilt binaries attached to the GitHub releases do not need a Haskell toolchain.
Build and test
cabal build all -fdevelopment
cabal test all -fdevelopment
The development flag turns warnings into errors, as CI does. Without it, cabal build and cabal test still work but do not enforce the warning gate.
Development
Run the formatter and linter with:
fourmolu --mode check src app test
hlint src app test
Install the pre-commit hook to scan staged changes for secrets:
pre-commit install
The hook requires gitleaks to be installed. The equivalent manual command is:
gitleaks git --staged --redact
Usage
The examples use the installed zim-to-markdown executable. From a repository checkout, replace zim-to-markdown with cabal run zim-to-markdown --.
Convert a single Zim page to standard output:
zim-to-markdown page.txt
Convert a single page to a Markdown file:
zim-to-markdown page.txt --output page.md
Collapse inline formatting that Markdown cannot express into emphasis:
zim-to-markdown page.txt --formatting bold
Use italic or strike for the other emphasis styles, or keep the default html for <u>, <sub> and <sup>.
Convert a whole Zim notebook, preserving its folders:
zim-to-markdown my-notebook --output my-notebook-markdown
The notebook directory or its notebook.zim file can be used as input:
zim-to-markdown my-notebook/notebook.zim --output my-notebook-markdown
Convert Markdown back to Zim:
zim-to-markdown --direction markdown-to-zim notes --output notes-zim
Run zim-to-markdown --help for the complete option list.
Releasing
Follow the release guide.
Status
The converter covers headings, emphasis, lists, task lists, links, images, anchors, tables, blockquotes, horizontal rules, and code blocks. Reference links, footnotes, nested links, raw HTML blocks, and Markdown indented code blocks are not converted yet. See conversion rules for details and known limitations, and the roadmap for the planned work.
License
BSD-3-Clause. See LICENSE.
