Metadata-Version: 2.4
Name: pandocster
Version: 2.1.1
Summary: Pandocster: a CLI helper around pandoc workflows, it helps you to build your documentation from markdown files.
Author-email: Leo Sadovsky <leo@sadovskie.ru>
License: MIT License
        
        Copyright (c) 2026 Leo Sadovsky
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: pandoc,pandocster,pandoc-filters,doc-as-code,documentation,markdown,pdf,html,docx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: types-click>=7.1.8; extra == "dev"
Dynamic: license-file

# Pandocster

Pandocster is a CLI helper around [pandoc](https://pandoc.org/) workflows. It builds a single document (PDF, HTML, and other formats) from a tree of Markdown files with minimal configuration.

## Quick start

```bash
$ pandocster check
$ pandocster build ./docs/md --to docx
```

The resulting DOCX (or other format) is written in the current directory; the default output name is derived from the current working directory unless you pass `--file-name`.

## What it does

- **Build** — Runs pandoc on the prepared tree with configurable options, metadata, and Lua filters. Includes built-in filters: `absorb_nonvisual_paragraphs`, `header_offset`, `link_anchors`, `newpage`. During preparation stage `Pandocster` builds a staging tree from a source Markdown directory: copies files, injects header-offset and anchor comments for structure, rewrites image links into a shared `resources/` directory, and preprocesses reference-style links.
- **Check** — `pandocster check` verifies that pandoc (≥3.8.3) and its Lua engine (≥5.4) are installed and sufficient.
- **Config** — Optional `pandocster.yaml` in the project directory or `~/.config/pandocster/config.yaml` globally. Use `pandocster config show` to print the effective config and `pandocster config create` to write a `pandocster.yaml` in the current directory.

## How it works

1. You simply run `pandocster build <src> --to <format>` (e.g. `pdf`, `html`) and you get standalone file.
2. Config is loaded from the current directory (`pandocster.yaml`), then global config, then built-in defaults.
3. **Build** collects all `.md` files under the build directory (with `_index.md` first per directory), runs pandoc with the configured filters and metadata, and writes the output in the current working directory as `<file-name>.<format>`. The build directory can be removed after success unless you pass `--preserve-build`.

## Installation

Install Pandocster with **pipx** so the tool runs in an isolated environment and the `pandocster` command is available globally:

```bash
pipx install pandocster
```

From a local clone:

```bash
pipx install .
```

You must have **pandoc** (and its built-in Lua engine) installed separately. Run `pandocster check` to verify versions.

- **Windows**: `winget install JohnMacFarlane.Pandoc`
- **Debian**: `sudo apt install pandoc.`
- **RHEL**: `# dnf install pandoc.`
- **Arch**: `pacman -S pandoc.`

And there are more ways to install, please refer to official documentation [https://pandoc.org/installing.html](https://pandoc.org/installing.html).

## Requirements

- Python ≥3.10
- pandoc ≥3.8.3 with Lua ≥5.4

## Commands


| Command                                        | Description                                      |
| ---------------------------------------------- | ------------------------------------------------ |
| `pandocster check`                             | Verify pandoc and Lua versions                   |
| `pandocster build <src> [build] --to <format>` | Prepare and render a document (e.g. `--to pdf`)  |
| `pandocster config show`                       | Print effective config as YAML                   |
| `pandocster config create`                     | Write `pandocster.yaml` in the current directory |


