manuscripta 0.6.0

Book production pipeline for authors and self-publishers. Multi-format export (PDF, EPUB, DOCX, HTML, Markdown), audiobook generation, translation, and manuscript tooling.

manuscripta

Book production pipeline for authors and self-publishers.

Multi-format export (PDF, EPUB, DOCX, HTML, Markdown), audiobook generation, translation, and manuscript tooling, powered by Pandoc.

Installation

pip install manuscripta

Or with Poetry:

poetry add manuscripta

Requirements

• Python 3.11+
• Pandoc installed and available on PATH
• For audiobook generation: internet connection (Edge TTS) or local TTS engine

Quick Start

Inside your book repository root:

# Export to PDF
export-pdf

# Export to EPUB with cover
export-ewc --cover assets/covers/cover.jpg

# Export all formats
export-all

# Safe export (no source modifications, good for drafts)
export-pdf-safe

# Generate audiobook
manuscripta-audiobook --engine edge --voice en-US-JennyNeural

# Initialize a new book project
manuscripta-init

Book Repository Structure

Each book repository should follow this layout:

my-book/
  manuscript/
    front-matter/
      toc.md
      toc-print.md
      foreword.md
      preface.md
    chapters/
      01-chapter-one.md
      02-chapter-two.md
    back-matter/
      epilogue.md
      glossary.md
      acknowledgments.md
      about-the-author.md
      bibliography.md
      imprint.md
  config/
    metadata.yaml
    export-settings.yaml
    voice-settings.yaml
  assets/
    covers/
    images/
    fonts/
    templates/
  output/
  pyproject.toml

Configuration

export-settings.yaml

Controls output formats, TOC behavior, and section ordering per book type (ebook, paperback, hardcover, audiobook).

voice-settings.yaml

TTS configuration: language, voice, and sections to skip during audio generation.

metadata.yaml

Pandoc metadata: title, author, date, language.

Available Commands

Export

Command	Description
export-pdf / export-p	Export PDF
export-epub / export-e	Export EPUB
export-docx / export-d	Export DOCX
export-html / export-h	Export HTML
export-md	Export Markdown
export-all	Export all formats
export-all-with-cover	Export all with cover
export-pvp	Print version (paperback)
export-pvh	Print version (hardcover)

All export commands have a -safe variant (e.g. export-pdf-safe) that skips source preprocessing for fast, non-destructive draft builds.

Audiobook

Command	Description
manuscripta-audiobook	Generate MP3 audiobook

Translation

Command	Description
translate-en-de	English to German (DeepL)
translate-de-en	German to English (DeepL)
translate-en-es	English to Spanish (DeepL)
translate-de-es	German to Spanish (DeepL)
translate-book-en-de	English to German (LMStudio)
translate-book-de-en	German to English (LMStudio)
translate-book-en-es	English to Spanish (LMStudio)
translate-book-en-fr	English to French (LMStudio)

Markdown Tools

Command	Description
fix-german-quotes	Fix German quotation marks
replace-md-bullet-points	Replace markdown bullet points
unbold-md-headers	Remove bold from headers
replace-emojis	Replace emojis in markdown
strip-links	Strip links from markdown
normalize-toc	Normalize TOC links

Path Tools

Command	Description
convert-paths-to-absolute	Convert relative paths to absolute
convert-paths-to-relative	Convert absolute paths to relative

Image Tools

Command	Description
convert-images	Convert image formats
generate-images	Generate images
generate-images-deepai	Generate images via DeepAI
inject-images	Inject images into manuscript

Project Management

Command	Description
manuscripta-init	Initialize new book project
create-chapters	Create chapter files
reorder-chapters	Reorder and rename chapters
update-metadata-values	Update metadata values
manuscripta-tag	Generate release tag message

Utilities

Command	Description
pandoc-batch	Batch pandoc conversion
bulk-change-ext	Bulk change file extensions
clean-git-cache	Clean git cache

Module Structure

manuscripta/
  export/        # PDF, EPUB, DOCX, HTML, Markdown export
  audiobook/     # TTS-based audiobook generation
    tts/         # Pluggable TTS backends (Edge, gTTS, pyttsx3, ElevenLabs)
  translation/   # DeepL and LMStudio translation
  markdown/      # Markdown processing (quotes, links, emojis, TOC)
  paths/         # Path conversion (absolute/relative, image tags)
  images/        # Image conversion, generation, injection
  project/       # Project init, chapters, metadata, tagging
  config/        # Config file loading
  enums/         # Book type enum
  utils/         # Pandoc batch, git cache, bulk operations
  data/          # Emoji/symbol maps, JSON data files

Development

Setup

git clone https://github.com/astrapi69/manuscripta.git
cd manuscripta
make lock-install

Make Targets

Run make help for a full list. Key targets:

Target	Description
make install	Install project with all dependencies
make lock-install	Lock and install project dependencies
make update	Update dependencies
make hooks	Install pre-commit hooks
make test	Run all tests
make test-v	Run all tests (verbose)
make test-fast	Run tests without coverage (faster)
make test-cov	Run tests with coverage report
make lint	Run ruff linter
make lint-fix	Run ruff linter with auto-fix
make format	Format code with black
make format-check	Check formatting without changes
make typecheck	Run MyPy type checks
make codespell	Run codespell
make precommit	Run all pre-commit hooks
make ci	Full CI pipeline (lint + format-check + test)
make bump-patch	Bump patch version (0.1.0 -> 0.1.1)
make bump-minor	Bump minor version (0.1.0 -> 0.2.0)
make bump-major	Bump major version (0.1.0 -> 1.0.0)
make tag-message	Generate tag message and create tag
make build	Build distribution package
make publish	Run CI, build and publish to PyPI
make publish-test	Run CI, build and publish to TestPyPI
make clean	Remove build artifacts and caches
make clean-venv	Remove Poetry virtualenv

Running Tests

# All tests with coverage
make test

# Quick run without coverage
make test-fast

# Full CI check before committing
make ci

Publishing

# Test release
make publish-test

# Production release
make publish

Both targets run the full CI pipeline (lint, format-check, tests) before building and publishing.

Companion Tools

• manuscript-tools - Validation, sanitization and metrics for Markdown manuscripts. Install separately for linting capabilities.

License

MIT