# Command line interface
## Usage
```text
zim-to-markdown [--direction DIRECTION] [--output PATH] INPUT
zim-to-markdown --help
zim-to-markdown --version
```
The examples use the installed `zim-to-markdown` executable. From a repository checkout, replace `zim-to-markdown` with `cabal run zim-to-markdown --`.
## Options
| Option | Meaning |
| --- | --- |
| `-d DIRECTION`, `--direction DIRECTION` | `zim-to-markdown` (default) or `markdown-to-zim`. |
| `-o PATH`, `--output PATH` | Output file for a single page; output directory for a notebook. |
| `--images MODE` | External images: `copy` (default), `symlink` or `relative`; notebook conversion only. |
| `-h`, `--help` | Show usage information. |
| `-V`, `--version` | Show the application version. |
## Single pages
When `INPUT` is a file, the result goes to standard output unless `--output` is given. In that case `PATH` must be a file path.
```sh
zim-to-markdown page.txt
zim-to-markdown page.txt --output page.md
zim-to-markdown --direction markdown-to-zim page.md --output page.txt
```
## Notebooks
When `INPUT` is a directory, it is treated as a notebook. A file named `notebook.zim` is also accepted; its parent directory becomes the notebook root. In both cases `--output` is required and the whole tree is converted recursively:
- Page files are converted to the target extension (`.txt` to `.md`, or `.md` and `.markdown` to `.txt`).
- Other files are copied unchanged, preserving their relative paths.
- Images referenced outside the notebook with `~` or an absolute path follow `--images`: `copy` stores them in `_assets/`, `symlink` stores absolute symbolic links in `_assets/`, and `relative` links to the originals with `..` segments. Links are written relative to each page; missing images keep the cleaned path, without the display options.
- The root `notebook.zim` file is treated as metadata and is not copied.
- Internal links are resolved using every page found in the notebook.
- Hidden files and symbolic links are skipped.
- Empty directories are not recreated.
- The output directory must not be inside the input directory.
`symlink` and `relative` require a notebook input. `markdown-to-zim` accepts only `copy`. The generated `_assets/` directory is reserved for external images; assets inside the notebook keep their own paths.
`symlink` needs symbolic-link support: on Windows it requires Developer Mode or Administrator privileges, and backup or archive tools may dereference or skip the links. These modes read the paths written in the notebook, so only convert notebooks from a trusted source; the output can copy files from outside the notebook and the symlinks reveal absolute paths.
```sh
zim-to-markdown my-notebook --output my-notebook-markdown
zim-to-markdown my-notebook/notebook.zim --output my-notebook-markdown
zim-to-markdown --direction markdown-to-zim notes --output notes-zim
```
## Exit status
The process exits with `0` on success and with a non-zero status when the arguments are invalid or when an input or output operation fails.