The poly command compiles .poly files to HTML, PDF, and SVG. Supports multi-file builds, theming, and file watching.
npm install -g polyesterThis gives you the poly command. You can also run it directly from a local install:
node dist/cli/index.js build document.polyCommand | Description |
|---|---|
poly build | Compile .poly files to HTML, PDF, or SVG |
poly watch | Watch a file and recompile on changes |
poly help | List all components or show help for one |
poly theme import | Import a colorscheme as a syntax theme |
poly theme list | List available themes |
poly style list | List available style modules |
poly spacing list | List available spacing presets |
poly build <input.poly...> [-o output] [--format html|pdf|svg] [--theme name]Compiles one or more .poly files. With a single file, you can specify an output path with -o. With multiple files, each produces an output file with the same name and a new extension.
poly build report.poly
poly build report.poly -o out.html
poly build report.poly --format pdf -o report.pdfOutput defaults to report.html (or .pdf/.svg based on --format).
poly build docs/*.poly
poly build a.poly b.poly c.poly
poly build docs/badges/*.poly --padding 0Shell glob expansion handles wildcards. The -o flag is not allowed with multiple inputs.
Flag | Description |
|---|---|
-o, --output <file> | Output file path (single input only) |
-f, --format <fmt> | Output format: html (default), pdf, svg |
-t, --theme <name> | Composed theme (style + spacing + syntax) |
--style <name> | Style module (colors, fonts, borders, shadows) |
--spacing <name> | Spacing module: compact, default, spacious |
--width <px> | SVG viewport width (default 800) |
--padding <px> | SVG padding |
--background <color> | SVG background color (use none for transparent) |
Flags apply to all files in a multi-file build. This is useful for batch operations like building badges with shared settings.
Default format. Produces a standalone HTML file with embedded CSS, syntax highlighting, and all styles inlined.
poly build doc.polyRenders HTML through Chrome via Puppeteer. Supports /page settings for paper size, margins, and pageless mode.
poly build doc.poly --format pdfRenders content as an SVG image. Useful for README badges, social cards, and embeddable graphics.
poly build doc.poly --format svgThree composable modules control the look of your documents.
# Use a composed theme
poly build doc.poly --theme gruvbox
# Mix individual modules
poly build doc.poly --style corporate --spacing compact
# Import a terminal colorscheme
poly theme import ~/.Xresources --name my-theme
poly build doc.poly --theme my-themeColors, fonts, borders, and shadows. Sets the visual identity of the document.
Margins, padding, and gaps. Controls density — compact, default, or spacious.
Code block colors. Imported from terminal colorschemes or built-in presets.
poly watch <input.poly> [--format html|pdf]Watches a single file for changes and recompiles automatically. Useful during development alongside a browser with live reload.
poly watch document.poly
poly watch slides.poly --format pdfpoly help # List all 27 components
poly help columns # Show detailed help for /columns
poly help --json # Output as JSON (for tooling)Displays component documentation including arguments, flags, descriptions, and examples. The --json flag outputs structured data for editor extensions and the MCP server.
Import colorschemes from terminal emulators and other tools.
poly theme import <file> --name <name> [--format <format>]Format | Source |
|---|---|
xresources | ~/.Xresources files |
pywal | pywal color files |
base16 | Base16 YAML schemes |
kitty | Kitty terminal config |
alacritty | Alacritty TOML/YAML config |
The format is auto-detected from the file when possible. Use --format to override.