Zine Arranger CLI

A command-line tool to convert PDFs into zine arrangements for printing. This tool takes PDF files and rearranges the pages so they can be printed, folded, and bound into a zine (small booklet).

Features

• Single PDF conversion: Convert one PDF into a zine arrangement
• Combined PDFs: Merge multiple PDFs and create a single zine
• Bulk processing: Process multiple PDFs into individual zines
• Multiple zine sizes (eighth, quarter, half, etc.)
• Single or double-sided printing support
• Portrait and landscape orientations
• Custom paper sizes

Installation

For Development

cd cli
npm install
npm run build

Global Installation (from npm)

npm install -g zine-arranger

Using npx (No Installation Required)

# Run directly without installing
npx zine-arranger single input.pdf output.pdf --size eighth --double-sided

Local Installation for Development

npm link

Configuration

RC File Support

You can create a configuration file to set default options. The CLI will look for configuration in the following locations (in order of precedence):

1. .zinearrangerrc in the current directory
2. .zinearrangerrc in your home directory
3. ~/.config/zinearranger/config
4. /etc/zinearrangerrc

The configuration file can be in JSON or INI format:

JSON format (.zinearrangerrc):

{
  "size": "eighth",
  "doubleSided": true,
  "portrait": true,
  "spineSide": true,
  "flipBackCover": true,
  "paperWidth": "8.5",
  "paperHeight": "11",
  "paperUnit": "in"
}

INI format (.zinearrangerrc):

size=eighth
doubleSided=true
portrait=true
spineSide=true
flipBackCover=true
paperWidth=8.5
paperHeight=11
paperUnit=in

Command-line options will override RC file settings.

Usage

Single PDF Conversion

Convert a single PDF into a zine:

zine-arranger single input.pdf output.pdf

With options:

zine-arranger single input.pdf output.pdf \
  --size eighth \
  --double-sided \
  --portrait

Combine Multiple PDFs

Merge multiple PDFs into a single zine:

zine-arranger combine output.pdf file1.pdf file2.pdf file3.pdf

Using glob patterns:

zine-arranger combine output.pdf "chapters/*.pdf"

Bulk Processing

Process multiple PDFs into individual zines:

zine-arranger bulk output-dir file1.pdf file2.pdf file3.pdf

With glob patterns:

zine-arranger bulk output-dir "input/*.pdf"

Options

Common Options

• -s, --size <size>: Zine size (default: eighth)

  • half: Half-size (4 pages per sheet)
  • quarter: Quarter-size (4-8 pages per sheet)
  • eighth or 8th: Eighth-size / Mini-zine (8-16 pages per sheet)
  • 12th: 1/12th size (12-24 pages per sheet)
  • 16th: 1/16th size (16-32 pages per sheet)
  • 24th, 32nd, 36th, 48th, 64th: Smaller sizes

• -d, --double-sided: Create double-sided zine (default: false)

• -p, --portrait: Zine is portrait orientation (default: true)

• --spine-side: Spine is on the side (default: true)

• --flip-back-cover: Flip back cover for top-fold zines (default: true)

Paper Size Options

• --paper-width <width>: Paper width (default: 8.5)
• --paper-height <height>: Paper height (default: 11)
• --paper-unit <unit>: Paper unit - in or mm (default: in)

For A4 paper:

zine-arranger single input.pdf output.pdf \
  --paper-width 210 \
  --paper-height 297 \
  --paper-unit mm

Examples

Basic Mini-Zine (Eighth Size, Single-Sided)

This is the most common zine format:

zine-arranger single story.pdf story-zine.pdf --size eighth

Print the output, fold it in half, cut along the center fold, and you have an 8-page mini-zine!

Double-Sided Quarter-Size Zine

zine-arranger single comic.pdf comic-zine.pdf \
  --size quarter \
  --double-sided

Combine Multiple Documents

zine-arranger combine anthology.pdf \
  "stories/*.pdf" \
  --size eighth \
  --double-sided

Process Multiple Files in Bulk

zine-arranger bulk zines/ *.pdf \
  --size eighth

This creates individual zine PDFs for each input file in the zines/ directory.

How It Works

The tool rearranges PDF pages according to traditional zine folding patterns:

1. Loads the input PDF(s) and counts the pages
2. Pads with blank pages if needed (page count must be a multiple of the zine size)
3. Arranges pages according to the zine folding algorithm
4. Scales and positions each page on the output sheets
5. Saves the arranged PDF ready for printing

The arrangement algorithm closely matches the web version at https://codeberg.org/nashhigh/zine-arranger to ensure compatibility.

Algorithm Details

The tool uses the same page arrangement algorithms as the web version:

• Eighth size (mini-zine): 8 pages per sheet when single-sided, 16 when double-sided
• Quarter size: 4 pages per sheet when single-sided, 8 when double-sided
• Half size: 4 pages per sheet

Each size has specific arrangements for:

• Portrait vs. landscape orientation
• Side-spine vs. top-spine binding
• Single-sided vs. double-sided printing

Development

Build the project:

npm run build

Run without building:

npm run dev -- single input.pdf output.pdf

Clean build files:

npm run clean

Troubleshooting

"No input files found"

• Check that your file paths are correct
• Use quotes around glob patterns: "*.pdf"

Blank pages at the end

• This is normal! Zines require page counts to be multiples of the zine size
• The blank pages ensure proper folding

Pages in wrong order

• Make sure you're using the correct size option
• Check portrait vs. landscape settings
• Verify spine-side vs. top-spine binding

Publishing

Prepare for Publishing

The package is configured for npm publishing with:

• prepublishOnly script that builds and tests before publishing
• .npmignore to exclude development files
• Proper files field in package.json to include only necessary files

Publish to npm

# Login to npm (first time only)
npm login

# Bump version (patch, minor, or major)
npm version patch

# Publish to npm
npm publish

Test Before Publishing

# Run all tests
npm test

# Test the package locally
npm pack
npm install -g ./zine-arranger-1.0.0.tgz

Using with npx

Once published, users can run without installing:

npx zine-arranger single input.pdf output.pdf --size eighth

License

MIT

Credits

Based on the web version of Zine Arranger by nashhigh (repo)