README

PHP CLI for Markdown book projects. One content/ tree becomes PDF, EPUB, HTML, a multi-page site, sample PDFs, and Amazon KDP deliverables.

Influenced by ibis-next, with first-class extras for sites, Mermaid, multi-script fonts, drafts, and KDP. Book roots use papyrus.php (or .yml / .json), content/, and assets/. Themes, CSS, and fonts ship bundled; publish them locally only when you need to customize.

Handbook · Packagist · GitHub

Features

• Site — build:site + serve: sidebar, ranked popup search, heading permalinks, sitemap/robots, light/dark, 404.html (GitHub Pages / Netlify ready)
• KDP — Kindle EPUB, print interior, wraparound cover PDF, metadata, package zip (kdp / kdp:*)
• PDF / EPUB / HTML — light & dark themes, --parallel PDF builds, single-file HTML
• Writing — Mermaid at build time, draft chapters (draft: true), sample PDFs, multi-script fonts
• Tooling — doctor, watch, lint, sizes, asset:publish, migrate-ibis
• Caches — chapter HTML and Mermaid figures under .papyrus/; -e / --export for CI / docs/

Handbook

The sample book lives in examples/the-papyrus-handbook/. Prebuilt outputs are in docs/ and on GitHub Pages:

composer build:handbook   # PDF, sample, HTML, and site → docs/

Stability (1.x)

Stable across SemVer majors: CLI command names and common flags, documented config keys, and default export/ filenames. Theme HTML/CSS and internal PHP APIs may change in minor releases.

Requirements

• PHP 8.2+ with dom, gd, mbstring, zip, zlib
• Composer

Optional (skipped with a warning when missing):

# macOS example
brew install php composer mermaid-cli epubcheck
brew install --cask google-chrome
export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

papyrus doctor

Linux: install Chromium or Chrome, set PUPPETEER_EXECUTABLE_PATH, and put epubcheck on PATH. Details are in the install chapter.

Install

Per project (recommended)

composer require milon/papyrus
vendor/bin/papyrus init
vendor/bin/papyrus doctor

Optional Composer scripts: "build": "papyrus build", "build:site": "papyrus build:site", and so on.

{
  "scripts": {
    "build": "papyrus build",
    "build:pdf": "papyrus build:pdf --theme light,dark",
    "build:epub": "papyrus build:epub",
    "build:html": "papyrus build:html",
    "build:site": "papyrus build:site",
    "build:sample": "papyrus build:sample",
    "build:kdp": "papyrus kdp"
  }
}

composer build
composer build:site

Global CLI

composer global require milon/papyrus
export PATH="$(composer global config bin-dir --absolute):$PATH"
papyrus list

From this repository

composer install
./bin/papyrus list

Quick start

papyrus init                 # or: --format=yml|yaml|json
papyrus doctor
papyrus build:site
papyrus serve               # http://127.0.0.1:8000/ — needed for site search

New folder: papyrus init -d my-book then pass -d my-book to other commands.

mkdir my-book && papyrus init -d my-book
papyrus doctor -d my-book
papyrus build:site -d my-book

Open export/<slug>-site/index.html in a browser, or deploy that folder as a static site.

init writes papyrus.php by default (--format=yml or json for papyrus.yml / papyrus.json). It also creates an empty assets/ directory. To customize the bundled theme or fonts later:

papyrus asset:publish
papyrus asset:publish --only=themes

Commands

Shared flags: -d / --dir, -e / --export, --include-drafts. Full options: handbook command reference.

$project = Milon\Papyrus\Config\Project::load($bookDir);
$book = $project->bookWithFigures(breakLevel: 1, exportTheme: 'html'); // drafts omitted
$withDrafts = $project->withIncludeDrafts()->bookWithFigures(breakLevel: 1, exportTheme: 'html');

Development

composer test
composer lint    # Pint --test
composer format  # Pint

Changelog

CHANGELOG.md

License

MIT — LICENSE.