Install and project layout

#Requirements

Required

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

Optional

macOS (Homebrew)

brew install php composer
brew install mermaid-cli
brew install --cask google-chrome
brew install epubcheck

export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

npm / Linux

npm install -g @mermaid-js/mermaid-cli
# Debian/Ubuntu example:
sudo apt-get install -y chromium-browser
export PUPPETEER_EXECUTABLE_PATH="$(command -v chromium-browser || command -v google-chrome || command -v chromium)"

Install epubcheck and put it on PATH, or use brew install epubcheck on macOS.

Check the toolchain

php -m | grep -E 'dom|gd|mbstring|zip|zlib'
mmdc --version
epubcheck --version
papyrus doctor

#Install per project

In your book repository:

composer require milon/papyrus

vendor/bin/papyrus --version
vendor/bin/papyrus init
vendor/bin/papyrus doctor

Wire Composer scripts (example):

{
  "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",
    "doctor": "papyrus doctor"
  }
}

Package page: packagist.org/packages/milon/papyrus.

#Install globally

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

#Scaffold a book

papyrus init
papyrus init -d my-book

init creates papyrus.php, content/, and an empty assets/ directory. Papyrus uses bundled themes, CSS, and fonts by default. Publish those files into your project only when you want to customize them:

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

Use --force / -f to overwrite files during init, or with asset:publish to overwrite published assets. --only limits publishing to themes, css, and/or fonts.

#Layout

Always run from the book root, or pass -d / --dir. Override where artifacts are written with -e / --export (default: <book>/export):

papyrus doctor -d /path/to/book
papyrus build --dir /path/to/book
papyrus build:site -d /path/to/book -e /path/to/out

Browse the Papyrus source on GitHub if you want to follow along with this handbook’s own project under examples/the-papyrus-handbook/.