# 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 notebook assets 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> (available after the first publication)
- GitHub: <https://github.com/Tralen/zim-to-markdown>
## Documentation
- [Architecture](docs/architecture.md)
- [Domain model](docs/domain.md)
- [Command line interface](docs/cli.md)
- [Conversion rules](docs/conversion.md)
- [Release guide](docs/releasing.md)
- [Versioning](docs/versioning.md)
- [Changelog](CHANGELOG.md)
## Installation
After the first Hackage publication, install with:
```sh
cabal install zim-to-markdown
```
## Prebuilt binaries
Prebuilt Linux, macOS, and Windows binaries are attached to [GitHub releases](https://github.com/Tralen/zim-to-markdown/releases/latest). 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
- GHC 9.14.1
- cabal-install 3.18.1.0
## Build and test
```sh
cabal build
cabal test
```
## Development
Run the formatter and linter with:
```sh
fourmolu --mode check src app test
hlint src app test
```
Install the pre-commit hook to scan staged changes for secrets:
```sh
pre-commit install
```
The hook requires `gitleaks` to be installed. The equivalent manual command is:
```sh
gitleaks git --staged --redact
```
## Usage
Convert a single Zim page to standard output:
```sh
cabal run zim-to-markdown -- page.txt
```
Convert a single page to a Markdown file:
```sh
cabal run zim-to-markdown -- page.txt --output page.md
```
Convert a whole Zim notebook, preserving its folders:
```sh
cabal run zim-to-markdown -- my-notebook --output my-notebook-markdown
```
The notebook directory or its `notebook.zim` file can be used as input:
```sh
cabal run zim-to-markdown -- my-notebook/notebook.zim --output my-notebook-markdown
```
Convert Markdown back to Zim:
```sh
cabal run zim-to-markdown -- --direction markdown-to-zim notes --output notes-zim
```
Run `cabal run zim-to-markdown -- --help` for the complete option list.
## Releasing
Follow the [release guide](docs/releasing.md).
## 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](docs/conversion.md) for details and known limitations.
## License
BSD-3-Clause. See [LICENSE](LICENSE).