122 lines
3.1 KiB
Markdown
122 lines
3.1 KiB
Markdown
|
# @stevanfreeborn/png2pdf
|
||
|
|
|
||
|
|
Convert PNG images to PDF files from the command line.
|
||
|
|
|
||
|
|
## Requirements
|
||
|
|
|
||
|
|
- Node.js 20 or newer
|
||
|
|
- npm
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
Run without installing:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
npx @stevanfreeborn/png2pdf .\image.png
|
||
|
|
```
|
||
|
|
|
||
|
|
Install globally:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
npm install --global @stevanfreeborn/png2pdf
|
||
|
|
png2pdf --help
|
||
|
|
```
|
||
|
|
|
||
|
|
## Local development
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
cd C:\Users\sfree\Repositories\png2pdf
|
||
|
|
npm install
|
||
|
|
npm run build
|
||
|
|
```
|
||
|
|
|
||
|
|
Run the local development build directly:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
npm run dev -- .\image.png
|
||
|
|
```
|
||
|
|
|
||
|
|
Or link the built CLI so `png2pdf` is available on your PATH:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
npm link
|
||
|
|
png2pdf --help
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```text
|
||
|
|
png2pdf <input...> [options]
|
||
|
|
```
|
||
|
|
|
||
|
|
Inputs can be PNG files, directories, or glob patterns. PNG extensions are
|
||
|
|
matched case-insensitively. Directory inputs are non-recursive unless
|
||
|
|
`--recursive` is supplied.
|
||
|
|
|
||
|
|
### Examples
|
||
|
|
|
||
|
|
Create a PDF beside each PNG:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
png2pdf .\screenshots\login.png
|
||
|
|
png2pdf .\screenshots
|
||
|
|
```
|
||
|
|
|
||
|
|
Write batch output to a directory:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
png2pdf ".\screenshots\**\*.png" --recursive --out-dir .\pdfs
|
||
|
|
```
|
||
|
|
|
||
|
|
Combine images into one multi-page PDF:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
png2pdf ".\screenshots\*.png" --merge --output .\album.pdf
|
||
|
|
```
|
||
|
|
|
||
|
|
Fit images onto A4 pages with a margin:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
png2pdf .\diagram.png --page-size a4 --margin 18
|
||
|
|
```
|
||
|
|
|
||
|
|
## Options
|
||
|
|
|
||
|
|
| Option | Description |
|
||
|
|
| --------------------- | ------------------------------------------------ |
|
||
|
|
| `-d, --out-dir <dir>` | Write batch PDFs to this directory. |
|
||
|
|
| `-m, --merge` | Combine all PNGs into one multi-page PDF. |
|
||
|
|
| `-o, --output <file>` | Output path for merged mode. Requires `--merge`. |
|
||
|
|
| `-r, --recursive` | Recurse into directory inputs. |
|
||
|
|
| `--page-size <size>` | `fit`, `a4`, or `letter`. Defaults to `fit`. |
|
||
|
|
| `--margin <points>` | Page margin in PDF points. Defaults to `0`. |
|
||
|
|
| `--dpi <number>` | DPI used to size `fit` pages. Defaults to `96`. |
|
||
|
|
| `-f, --force` | Overwrite existing output files. |
|
||
|
|
| `-q, --quiet` | Suppress success and progress output. |
|
||
|
|
| `-V, --version` | Print the version. |
|
||
|
|
| `-h, --help` | Print help. |
|
||
|
|
|
||
|
|
## Behavior
|
||
|
|
|
||
|
|
- By default, every PNG becomes its own PDF beside the source file.
|
||
|
|
- With `--merge`, all PNGs become pages in one PDF, in sorted path order.
|
||
|
|
- `fit` pages use the image's physical dimensions at the selected DPI plus
|
||
|
|
margins.
|
||
|
|
- `a4` and `letter` pages fit and center the image while preserving its aspect
|
||
|
|
ratio. Page orientation follows the image orientation.
|
||
|
|
- Transparent PNGs keep their alpha channel.
|
||
|
|
- Existing files are not overwritten unless `--force` is used.
|
||
|
|
- In batch mode, failures are reported without stopping other conversions. The
|
||
|
|
command exits with code `1` if any conversion fails.
|
||
|
|
- Batch output collisions, such as two inputs with the same basename and one
|
||
|
|
output directory, are rejected before conversion starts.
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
npm run typecheck
|
||
|
|
npm run lint
|
||
|
|
npm test
|
||
|
|
npm run build
|
||
|
|
npm run format:check
|
||
|
|
```
|