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 to #, ##, and ###.
• Copies or links external images with --images copy|symlink|relative, so images and attachments keep working.
• 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

• Hackage: https://hackage.haskell.org/package/zim-to-markdown
• GitHub: https://github.com/Tralen/zim-to-markdown

Documentation

• Architecture
• Domain model
• Command line interface
• Conversion rules
• Release guide
• Roadmap
• Versioning
• Changelog

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. Build from source for other Linux distributions.

Requirements

Building from source or installing with cabal install requires:

• GHC 9.14.1
• cabal-install 3.18.1.0

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
cabal test

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

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.