mdbindery 0.1.0__tar.gz

mdbindery-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (2026-09-26)
+
+First public release.
+
+- `mdbindery build`: turns a folder or GitHub repository of Markdown chapters into an EPUB 3, one chapter per file. Supports links between files with GitHub anchors, numbered citations linked to a generated reference list, footnotes as numbered endnotes, figures and full-page images, a supplied or generated cover, Mermaid charts rendered to PNG, wide tables as cards, GitHub alerts, math as MathML, code highlighting, and GitHub-style HTML.
+- Repairs for common repository layouts: a chapter title for files without a level-1 heading, content above the title moved below it, anchors moved out of headings, links to files outside the book pointed at `source_url` (or kept as text), `.html` links resolved to `.md` files, and image URLs of the same repository replaced by the local files.
+- Reading order from `files:` in `mdbindery.yaml`, or inferred from a table of contents file, the README's links, or the file names (with front and back matter recognized).
+- mdBook books: `book.toml`, `SUMMARY.md`, `{{#include}}` and related directives, and hidden lines in Rust code.
+- Gates that fail the build: links, images, charts, includes, EPUBCheck, DAISY Ace, and a per-file word count that catches lost or duplicated text. Output is reproducible, and the EPUB carries accessibility metadata.
+- `mdbindery check`: a dry run for a local folder, a GitHub URL, or another git URL, with a Markdown or JSON report (MB codes, file, line, and a fix for each finding), a suggested configuration, and an optional trial build.
+- `mdbindery init`, `install-tools`, `doctor`, and `preview` (phone-size screenshots).
+- Installers for Linux, macOS, and Windows that need nothing preinstalled and no admin rights. uv, pandoc, EPUBCheck, and Node.js downloads are pinned and checksum-verified.
+- Packages on PyPI, a Homebrew tap (`sagol/tap`), and a GitHub Action (`uses: sagol/mdbindery@v0.1.0`) that installs mdbindery and its tools with caching.
+- Agent skills for running mdbindery and for preparing a repository for it.

mdbindery-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Baranyuk
+
+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.

mdbindery-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+graft tests
+graft examples
+global-exclude __pycache__ *.py[cod]
+prune examples/*/dist

mdbindery-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: mdbindery
+Version: 0.1.0
+Summary: Turn a folder or GitHub repository of Markdown chapters into a validated EPUB 3 ebook.
+Author: Taras Baranyuk
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sagol/mdbindery
+Project-URL: Documentation, https://github.com/sagol/mdbindery/tree/main/docs
+Project-URL: Changelog, https://github.com/sagol/mdbindery/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sagol/mdbindery/issues
+Keywords: epub,ebook,markdown,pandoc,publishing,book,epubcheck,mdbook
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Printing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: Pillow>=9.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# mdbindery
+
+Turn a folder or GitHub repository of Markdown chapters into a validated EPUB 3 ebook.
+
+mdbindery is built for books written the GitHub way: one Markdown file per chapter, relative links between files, images in the repository, citations as `[1]` with reference definitions. The book stays readable on GitHub, and the EPUB passes EPUBCheck and the DAISY Ace accessibility check without hand editing.
+
+```
+mdbindery check https://github.com/OWNER/REPO     # what to fix, file by file and line by line
+mdbindery build path/to/your-book                 # dist/<slug>.epub, validated
+```
+
+## What it does
+
+- Links between chapters, including links to headings in other files and custom `<a id>` anchors, become internal EPUB links. A link that has no target fails the build.
+- Citations written as `[1]` with `[1]: url "Title"` definitions (invisible on GitHub) become visible numbered reference lists with working links.
+- Images become inline icons, block images, figures with captions (the image title), or full-page images (`"full-page"` title). The cover can be any common image format, or mdbindery generates a typographic one. Missing and remote images fail the build.
+- Mermaid charts become PNG images with alt text taken from the chart.
+- Wide tables can become cards (one block per row), so they read on a phone.
+- Footnotes become numbered endnotes; math becomes MathML; GitHub alerts, task lists, and code blocks (with monochrome highlighting) are supported.
+- Raw HTML from GitHub READMEs (`<br>`, `<sup>`, `<img>`, `<p align>`, `<details>`, and more) becomes valid EPUB markup; tags with no EPUB equivalent are removed and reported.
+- mdBook books work as they are: `book.toml` gives the metadata, `SUMMARY.md` the reading order, and `{{#include}}` directives are expanded.
+- The book gets its title, subtitle, authors, language, rights, a permanent identifier, and schema.org accessibility metadata.
+- Builds are reproducible: the same commit built twice with the same tools gives byte-identical files.
+
+## Checking and validation
+
+`mdbindery check` is a dry run on a local folder or a repository URL. It changes nothing and prints a Markdown report: every problem with its code, severity (error, warning, or note), file, line, and fix; the reading order and where it came from; and, for a book without one, a suggested `mdbindery.yaml`. `--build` adds a trial build with all the gates, and `--json FILE` writes the same report as JSON. The exit status is 0 when there are no errors, 1 when there are, and 2 when the target cannot be read.
+
+`mdbindery build` writes the EPUB and then runs the gates: links, images, charts, mdBook includes, EPUBCheck, Ace, and a word count that catches text lost in conversion. If any gate fails, the build ends with `BUILD FAILED` and exit status 1; the EPUB is still written so you can inspect it. A missing Ace (after an install with `--no-node`) is a warning, not a failure.
+
+## Supported inputs
+
+- A folder of Markdown files, one per chapter. The reading order comes from `files:` in `mdbindery.yaml`, or else from a `SUMMARY.md` or other table-of-contents file, from the README's links when the chapter file names are not all numbered, or from the file names.
+- A GitHub repository. `mdbindery check` accepts `https://github.com/OWNER/REPO`, `.../tree/BRANCH/FOLDER` for a book in a subfolder, and other git URLs. To build it, clone it and build the folder.
+- An mdBook book, found by its `book.toml`.
+
+## Install
+
+Linux and macOS:
+
+```
+curl -fsSL https://raw.githubusercontent.com/sagol/mdbindery/main/install/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```
+irm https://raw.githubusercontent.com/sagol/mdbindery/main/install/install.ps1 | iex
+```
+
+The installer needs nothing preinstalled. It fetches [uv](https://github.com/astral-sh/uv), installs mdbindery in an isolated environment (with its own Python if needed), then downloads pandoc, EPUBCheck, a Java runtime if none is present, Node.js, mermaid-cli, and Ace into a per-user folder. pandoc, EPUBCheck, Node.js, and uv are pinned to exact versions and verified against SHA-256 checksums; the Java runtime comes from Eclipse Temurin's API with its published checksum; mermaid-cli and Ace are pinned by version. Nothing needs administrator rights, and nothing asks questions, so the same commands work in scripts and CI.
+
+To pin a release, pass its tag: `curl -fsSL https://raw.githubusercontent.com/sagol/mdbindery/v0.1.0/install/install.sh | bash -s -- --ref v0.1.0`.
+
+Other ways to install:
+
+| Channel | Command |
+|---|---|
+| PyPI (pipx, uv, pip) | `pipx install mdbindery` or `uv tool install mdbindery`, then `mdbindery install-tools` |
+| Homebrew (macOS, Linux) | `brew install sagol/tap/mdbindery`, then `mdbindery install-tools` |
+| GitHub Actions | `- uses: sagol/mdbindery@v0.1.0`, then run `mdbindery` in later steps |
+| Release files | wheel, source archive, and both installers on the [releases page](https://github.com/sagol/mdbindery/releases) |
+
+In a workflow:
+
+```yaml
+- uses: sagol/mdbindery@v0.1.0      # installs mdbindery and its tools, cached between runs
+- run: mdbindery build path/to/book  # exit 1 when a gate fails
+```
+
+Details, options, manual installation, and uninstalling: [docs/installation.md](https://github.com/sagol/mdbindery/blob/main/docs/installation.md).
+
+## Quick start
+
+```
+mdbindery doctor                                  # which tools are installed and working
+cd your-book
+mdbindery init                                    # write mdbindery.yaml from what it finds
+mdbindery check .                                 # fix what it reports
+mdbindery build                                   # dist/<slug>.epub and dist/reports/
+mdbindery preview dist/<slug>.epub shots          # phone-size screenshots
+```
+
+To try it on the sample book in this repository:
+
+```
+git clone https://github.com/sagol/mdbindery
+cd mdbindery/examples/sample-book
+mdbindery check . --build
+mdbindery build
+mdbindery preview dist/writing-a-book-in-markdown.epub shots
+```
+
+The full walk-through is in [docs/tutorial.md](https://github.com/sagol/mdbindery/blob/main/docs/tutorial.md).
+
+## Requirements
+
+- Linux (x64 or arm64, glibc-based), macOS (Intel or Apple silicon), or Windows 10/11 (x64 or arm64).
+- About 1.5 GB of disk for the full tool set; mermaid-cli, Ace, and their two headless Chrome builds take most of it. With `--no-node` (no charts, no Ace, no `preview`), a whole install including uv and Python took about 370 MB. A downloaded Java runtime adds about 130 MB.
+- An internet connection to install. Building works offline.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Tutorial](https://github.com/sagol/mdbindery/blob/main/docs/tutorial.md) | From an existing repository to a validated EPUB, step by step |
+| [Book structure rules](https://github.com/sagol/mdbindery/blob/main/docs/book-structure.md) | Files, headings, links, citations, images (cover, inline, figures, full-page), tables, charts |
+| [Configuration](https://github.com/sagol/mdbindery/blob/main/docs/configuration.md) | Every `mdbindery.yaml` key |
+| [Checking](https://github.com/sagol/mdbindery/blob/main/docs/checking.md) | `mdbindery check`, the report, and every check code with its fix |
+| [Building](https://github.com/sagol/mdbindery/blob/main/docs/building.md) | The pipeline, outputs, gates, reproducibility, covers, preview, uploading to stores |
+| [Installation](https://github.com/sagol/mdbindery/blob/main/docs/installation.md) | Linux, macOS, Windows, manual and offline setups, updating, uninstalling |
+| [Troubleshooting](https://github.com/sagol/mdbindery/blob/main/docs/troubleshooting.md) | Common errors and what to do |
+| [Design](https://github.com/sagol/mdbindery/blob/main/docs/design.md) | How it works inside, for contributors |
+
+## For AI coding agents
+
+[`skills/mdbindery-prepare-repo/SKILL.md`](https://github.com/sagol/mdbindery/blob/main/skills/mdbindery-prepare-repo/SKILL.md) teaches an LLM agent (Claude Code, Codex, Cursor, and similar) how to restructure a repository for mdbindery and loop on `mdbindery check` until it is clean. [`skills/mdbindery/SKILL.md`](https://github.com/sagol/mdbindery/blob/main/skills/mdbindery/SKILL.md) covers running the tool: installing, checking, building, previewing, and reading the reports. Both are plain Markdown and can be copied into any agent's skill or rules folder.
+
+## Credits
+
+mdbindery orchestrates [pandoc](https://pandoc.org), [EPUBCheck](https://www.w3.org/publishing/epubcheck/), [DAISY Ace](https://daisy.github.io/ace/), [mermaid-cli](https://github.com/mermaid-js/mermaid-cli), [Eclipse Temurin](https://adoptium.net), and [uv](https://github.com/astral-sh/uv). Each keeps its own license.
+
+## License
+
+MIT. See [LICENSE](https://github.com/sagol/mdbindery/blob/main/LICENSE).

mdbindery-0.1.0/README.md

@@ -0,0 +1,125 @@
+# mdbindery
+
+Turn a folder or GitHub repository of Markdown chapters into a validated EPUB 3 ebook.
+
+mdbindery is built for books written the GitHub way: one Markdown file per chapter, relative links between files, images in the repository, citations as `[1]` with reference definitions. The book stays readable on GitHub, and the EPUB passes EPUBCheck and the DAISY Ace accessibility check without hand editing.
+
+```
+mdbindery check https://github.com/OWNER/REPO     # what to fix, file by file and line by line
+mdbindery build path/to/your-book                 # dist/<slug>.epub, validated
+```
+
+## What it does
+
+- Links between chapters, including links to headings in other files and custom `<a id>` anchors, become internal EPUB links. A link that has no target fails the build.
+- Citations written as `[1]` with `[1]: url "Title"` definitions (invisible on GitHub) become visible numbered reference lists with working links.
+- Images become inline icons, block images, figures with captions (the image title), or full-page images (`"full-page"` title). The cover can be any common image format, or mdbindery generates a typographic one. Missing and remote images fail the build.
+- Mermaid charts become PNG images with alt text taken from the chart.
+- Wide tables can become cards (one block per row), so they read on a phone.
+- Footnotes become numbered endnotes; math becomes MathML; GitHub alerts, task lists, and code blocks (with monochrome highlighting) are supported.
+- Raw HTML from GitHub READMEs (`<br>`, `<sup>`, `<img>`, `<p align>`, `<details>`, and more) becomes valid EPUB markup; tags with no EPUB equivalent are removed and reported.
+- mdBook books work as they are: `book.toml` gives the metadata, `SUMMARY.md` the reading order, and `{{#include}}` directives are expanded.
+- The book gets its title, subtitle, authors, language, rights, a permanent identifier, and schema.org accessibility metadata.
+- Builds are reproducible: the same commit built twice with the same tools gives byte-identical files.
+
+## Checking and validation
+
+`mdbindery check` is a dry run on a local folder or a repository URL. It changes nothing and prints a Markdown report: every problem with its code, severity (error, warning, or note), file, line, and fix; the reading order and where it came from; and, for a book without one, a suggested `mdbindery.yaml`. `--build` adds a trial build with all the gates, and `--json FILE` writes the same report as JSON. The exit status is 0 when there are no errors, 1 when there are, and 2 when the target cannot be read.
+
+`mdbindery build` writes the EPUB and then runs the gates: links, images, charts, mdBook includes, EPUBCheck, Ace, and a word count that catches text lost in conversion. If any gate fails, the build ends with `BUILD FAILED` and exit status 1; the EPUB is still written so you can inspect it. A missing Ace (after an install with `--no-node`) is a warning, not a failure.
+
+## Supported inputs
+
+- A folder of Markdown files, one per chapter. The reading order comes from `files:` in `mdbindery.yaml`, or else from a `SUMMARY.md` or other table-of-contents file, from the README's links when the chapter file names are not all numbered, or from the file names.
+- A GitHub repository. `mdbindery check` accepts `https://github.com/OWNER/REPO`, `.../tree/BRANCH/FOLDER` for a book in a subfolder, and other git URLs. To build it, clone it and build the folder.
+- An mdBook book, found by its `book.toml`.
+
+## Install
+
+Linux and macOS:
+
+```
+curl -fsSL https://raw.githubusercontent.com/sagol/mdbindery/main/install/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```
+irm https://raw.githubusercontent.com/sagol/mdbindery/main/install/install.ps1 | iex
+```
+
+The installer needs nothing preinstalled. It fetches [uv](https://github.com/astral-sh/uv), installs mdbindery in an isolated environment (with its own Python if needed), then downloads pandoc, EPUBCheck, a Java runtime if none is present, Node.js, mermaid-cli, and Ace into a per-user folder. pandoc, EPUBCheck, Node.js, and uv are pinned to exact versions and verified against SHA-256 checksums; the Java runtime comes from Eclipse Temurin's API with its published checksum; mermaid-cli and Ace are pinned by version. Nothing needs administrator rights, and nothing asks questions, so the same commands work in scripts and CI.
+
+To pin a release, pass its tag: `curl -fsSL https://raw.githubusercontent.com/sagol/mdbindery/v0.1.0/install/install.sh | bash -s -- --ref v0.1.0`.
+
+Other ways to install:
+
+| Channel | Command |
+|---|---|
+| PyPI (pipx, uv, pip) | `pipx install mdbindery` or `uv tool install mdbindery`, then `mdbindery install-tools` |
+| Homebrew (macOS, Linux) | `brew install sagol/tap/mdbindery`, then `mdbindery install-tools` |
+| GitHub Actions | `- uses: sagol/mdbindery@v0.1.0`, then run `mdbindery` in later steps |
+| Release files | wheel, source archive, and both installers on the [releases page](https://github.com/sagol/mdbindery/releases) |
+
+In a workflow:
+
+```yaml
+- uses: sagol/mdbindery@v0.1.0      # installs mdbindery and its tools, cached between runs
+- run: mdbindery build path/to/book  # exit 1 when a gate fails
+```
+
+Details, options, manual installation, and uninstalling: [docs/installation.md](https://github.com/sagol/mdbindery/blob/main/docs/installation.md).
+
+## Quick start
+
+```
+mdbindery doctor                                  # which tools are installed and working
+cd your-book
+mdbindery init                                    # write mdbindery.yaml from what it finds
+mdbindery check .                                 # fix what it reports
+mdbindery build                                   # dist/<slug>.epub and dist/reports/
+mdbindery preview dist/<slug>.epub shots          # phone-size screenshots
+```
+
+To try it on the sample book in this repository:
+
+```
+git clone https://github.com/sagol/mdbindery
+cd mdbindery/examples/sample-book
+mdbindery check . --build
+mdbindery build
+mdbindery preview dist/writing-a-book-in-markdown.epub shots
+```
+
+The full walk-through is in [docs/tutorial.md](https://github.com/sagol/mdbindery/blob/main/docs/tutorial.md).
+
+## Requirements
+
+- Linux (x64 or arm64, glibc-based), macOS (Intel or Apple silicon), or Windows 10/11 (x64 or arm64).
+- About 1.5 GB of disk for the full tool set; mermaid-cli, Ace, and their two headless Chrome builds take most of it. With `--no-node` (no charts, no Ace, no `preview`), a whole install including uv and Python took about 370 MB. A downloaded Java runtime adds about 130 MB.
+- An internet connection to install. Building works offline.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Tutorial](https://github.com/sagol/mdbindery/blob/main/docs/tutorial.md) | From an existing repository to a validated EPUB, step by step |
+| [Book structure rules](https://github.com/sagol/mdbindery/blob/main/docs/book-structure.md) | Files, headings, links, citations, images (cover, inline, figures, full-page), tables, charts |
+| [Configuration](https://github.com/sagol/mdbindery/blob/main/docs/configuration.md) | Every `mdbindery.yaml` key |
+| [Checking](https://github.com/sagol/mdbindery/blob/main/docs/checking.md) | `mdbindery check`, the report, and every check code with its fix |
+| [Building](https://github.com/sagol/mdbindery/blob/main/docs/building.md) | The pipeline, outputs, gates, reproducibility, covers, preview, uploading to stores |
+| [Installation](https://github.com/sagol/mdbindery/blob/main/docs/installation.md) | Linux, macOS, Windows, manual and offline setups, updating, uninstalling |
+| [Troubleshooting](https://github.com/sagol/mdbindery/blob/main/docs/troubleshooting.md) | Common errors and what to do |
+| [Design](https://github.com/sagol/mdbindery/blob/main/docs/design.md) | How it works inside, for contributors |
+
+## For AI coding agents
+
+[`skills/mdbindery-prepare-repo/SKILL.md`](https://github.com/sagol/mdbindery/blob/main/skills/mdbindery-prepare-repo/SKILL.md) teaches an LLM agent (Claude Code, Codex, Cursor, and similar) how to restructure a repository for mdbindery and loop on `mdbindery check` until it is clean. [`skills/mdbindery/SKILL.md`](https://github.com/sagol/mdbindery/blob/main/skills/mdbindery/SKILL.md) covers running the tool: installing, checking, building, previewing, and reading the reports. Both are plain Markdown and can be copied into any agent's skill or rules folder.
+
+## Credits
+
+mdbindery orchestrates [pandoc](https://pandoc.org), [EPUBCheck](https://www.w3.org/publishing/epubcheck/), [DAISY Ace](https://daisy.github.io/ace/), [mermaid-cli](https://github.com/mermaid-js/mermaid-cli), [Eclipse Temurin](https://adoptium.net), and [uv](https://github.com/astral-sh/uv). Each keeps its own license.
+
+## License
+
+MIT. See [LICENSE](https://github.com/sagol/mdbindery/blob/main/LICENSE).

mdbindery-0.1.0/examples/sample-book/01-why-markdown.md

@@ -0,0 +1,23 @@
+# 1. Why Markdown
+
+*Scenario, a kitchen table, 2031.* The draft lives in a folder of plain text files. Nothing about it depends on one program.
+
+Markdown keeps a manuscript readable as plain text and renders cleanly on GitHub [1]. Pandoc can turn the same files into an EPUB 3 publication [2], the format most ebook stores accept.
+
+> [!NOTE]
+> This paragraph is a GitHub alert. In the EPUB it becomes a tinted box with a "Note" label.
+
+## Plain text lasts
+
+A text file written today will open in fifty years.[^durable] The icon ![Markdown icon](images/icon.png) sits inline with this sentence, and its alt text describes it for screen readers.
+
+![Four boxes in a row: Markdown, Checks, Pandoc, EPUB 3, joined by arrows](images/pipeline.png "From Markdown to EPUB in four steps")
+
+The image above has a title in its Markdown source, so it becomes a figure with a caption. [Chapter 2](02-structure.md#tables-and-code) shows the other building blocks.
+
+## References
+
+[1]: https://github.github.com/gfm/ "GitHub, GitHub Flavored Markdown Spec, version 0.29-gfm"
+[2]: https://pandoc.org/MANUAL.html "John MacFarlane, Pandoc User's Guide"
+
+[^durable]: Plain UTF-8 text is the most durable format a writer can choose.

mdbindery-0.1.0/examples/sample-book/02-structure.md

@@ -0,0 +1,33 @@
+# 2. Structure
+
+Every chapter file starts with one level-1 heading. Sections use `##`, subsections `###`, and levels are never skipped.
+
+## Tables and code
+
+| Element | Markdown | EPUB result |
+|---|---|---|
+| Table | pipes and dashes | an HTML table |
+| Code | three backticks | a preformatted block |
+| Math | `$...$` | MathML |
+
+```python
+def greet(name):
+    return f"Hello, {name}"
+```
+
+The area of a circle is $A = \pi r^2$.
+
+## A chart
+
+```mermaid
+flowchart LR
+  A[Draft] --> B[Check] --> C[Build] --> D[Publish]
+```
+
+## A full-page image
+
+The next image fills its own page in the EPUB, because its title starts with `full-page`.
+
+![A desk under a night sky full of stars](images/night-desk.jpg "full-page: Writing at night")
+
+Back to [chapter 1](01-why-markdown.md), or on to [publishing](03-publishing.md).

mdbindery-0.1.0/examples/sample-book/03-publishing.md

@@ -0,0 +1,22 @@
+# 3. Publishing
+
+Links between chapters use relative file paths, exactly as on GitHub. This one goes to [the plain-text section](01-why-markdown.md#plain-text-lasts), and this one to the [checklist](appendix-a-checklist.md#a1-before-you-build).
+
+## Inline HTML
+
+A few HTML tags are converted: press <kbd>Ctrl</kbd>+<kbd>S</kbd>, write H<sub>2</sub>O and E = mc<sup>2</sup>,<br>or break a line.
+
+## A task list
+
+- [x] Write the chapters
+- [x] Add the images
+- [ ] Run `mdbindery check`
+- [ ] Build the EPUB
+
+## Publishing checklist
+
+Validation matters because ebook stores reject files that fail EPUBCheck [1].
+
+## References
+
+[1]: https://www.w3.org/publishing/epubcheck/ "W3C, EPUBCheck"

mdbindery-0.1.0/examples/sample-book/LICENSE

@@ -0,0 +1,5 @@
+The text and images of this sample book are licensed under the Creative Commons
+Attribution 4.0 International License (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/
+
+SPDX-License-Identifier: CC-BY-4.0

mdbindery-0.1.0/examples/sample-book/README.md

@@ -0,0 +1,22 @@
+# Writing a Book in Markdown
+
+*A small sample book that shows every feature mdbindery supports.*
+
+This repository is a complete book. Read it on GitHub as Markdown, or build it into an EPUB with `mdbindery build`. Each chapter demonstrates one part of the structure rules, so you can copy what you need.
+
+## Contents
+
+| Chapter | What it shows |
+|---|---|
+| [1. Why Markdown](01-why-markdown.md) | Citations, footnotes, alerts, inline images, figures |
+| [2. Structure](02-structure.md) | Headings, tables, code, math, a Mermaid chart, a full-page image |
+| [3. Publishing](03-publishing.md) | Links between chapters, inline HTML, task lists |
+| [Appendix A. Checklist](appendix-a-checklist.md) | A wide table rendered as cards |
+
+## Contributing
+
+Pull requests are welcome. This section is for GitHub readers only; the book's config drops it from the EPUB.
+
+## License
+
+Text and images are licensed under [CC BY 4.0](LICENSE).

mdbindery-0.1.0/examples/sample-book/appendix-a-checklist.md

@@ -0,0 +1,12 @@
+# Appendix A. Checklist
+
+The table below has ten columns. On a phone that is unreadable, so the book's config renders it as cards: one block per row.
+
+## A1. Before you build
+
+| ID | Item | Where | Rule | Tool | Severity | Owner | Status | Notes | Link |
+|---|---|---|---|---|---|---|---|---|---|
+| C1 | One level-1 heading per file | Every chapter | Structure | check | Warning | Author | Done | First line of the file | [chapter 2](02-structure.md) |
+| C2 | Images have alt text | Every image | Accessibility | check, Ace | Warning | Author | Done | Describe what it shows | [chapter 1](01-why-markdown.md) |
+| C3 | Links resolve | Whole book | Navigation | check, build | Error | Editor | Done | Relative paths only | [chapter 3](03-publishing.md) |
+| C4 | Cover is 1600x2560 | images/cover.jpg | Stores | check | Warning | Designer | Done | JPEG, RGB | [README](README.md) |

mdbindery-0.1.0/examples/sample-book/mdbindery.yaml

@@ -0,0 +1,37 @@
+# mdbindery configuration for the sample book
+slug: writing-a-book-in-markdown
+output_dir: dist
+source_url: https://github.com/sagol/mdbindery/blob/main/examples/sample-book/
+
+metadata:
+  title: Writing a Book in Markdown
+  subtitle: A small sample book for mdbindery
+  authors: [Sample Author]
+  lang: en-US
+  identifier: urn:uuid:5f0f1c2e-8a4b-4d6e-9c1a-3b7e2d9f0a11
+  date: 2026-09-26
+  rights: Text and images licensed under CC BY 4.0
+  description: A short book that demonstrates every feature of mdbindery.
+  subjects: [Markdown, EPUB, Publishing]
+
+cover:
+  image: images/cover.jpg
+
+files:
+  - file: README.md
+    role: front
+    title: About this book
+    drop_sections: [Contributing]
+  - 01-why-markdown.md
+  - 02-structure.md
+  - 03-publishing.md
+  - file: appendix-a-checklist.md
+    role: appendix
+
+options:
+  citations: refdefs
+  toc_depth: 2
+  cards:
+    files: [appendix-a-checklist.md]
+    min_columns: 9
+    title_columns: 2

mdbindery-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mdbindery"
+dynamic = ["version"]
+description = "Turn a folder or GitHub repository of Markdown chapters into a validated EPUB 3 ebook."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Taras Baranyuk" }]
+keywords = ["epub", "ebook", "markdown", "pandoc", "publishing", "book", "epubcheck", "mdbook"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Markup :: Markdown",
+  "Topic :: Printing",
+]
+dependencies = ["PyYAML>=6.0", "Pillow>=9.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+mdbindery = "mdbindery.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sagol/mdbindery"
+Documentation = "https://github.com/sagol/mdbindery/tree/main/docs"
+Changelog = "https://github.com/sagol/mdbindery/blob/main/CHANGELOG.md"
+Issues = "https://github.com/sagol/mdbindery/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "mdbindery.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mdbindery = ["data/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mdbindery-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mdbindery-0.1.0/src/mdbindery/__init__.py

@@ -0,0 +1,2 @@
+"""mdbindery: Markdown chapters to validated EPUB 3."""
+__version__ = "0.1.0"

mdbindery-0.1.0/src/mdbindery/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())