html2image command

SYNOPSIS:
    Converts HTML files to images using Puppeteer.

USAGE: html2image [OPTIONS] [ARGUMENTS]
USAGE: html2image [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q] [--ci] [--format|-f <Format>] [--same-dir]
  [--output-dir|-d <OutputDir>] [--output|-o <OutputFile>]
  [--transform-cmd|-t <TransformCmd>] [--viewport <Viewport>]
  [--quality <Quality>] [--full-page] [--wait-for-render <Milliseconds>]
  [--wait-for-selector <Selector>] [--inject-css <CssFile>]
  [--hide-selector <Selector>] [--file-filter <Regex>]

ARGUMENTS:
  [HTMLFiles {list} (optional)]

    HTML files to convert.

    NO FILES:

    If not provided, all HTML files from git repository will be converted.

    STDIN:

    If '-' is provided, HTML content will be read from stdin.
    Incompatible with --output unless stdin is used.

    If using stdin, the option --output
    is required to specify the output file path.

    If using stdin, the option --same-dir and --output-dir cannot be used.

    If using stdin, the option --transform-cmd
    can be used to apply a transform command to the HTML content before
    conversion (the HTML content will be passed to the transform command
    via stdin).


GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/logs/html2image.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.

OPTIONS:
  --ci {single}
    Activate continuous integration mode (tmp folder not shared with host)

  --format, -f <Format> {list} (optional)
    Output image format (default: webp if not provided)
    Possible values: 
      - png: PNG raster format
      - jpg: JPEG raster format
      - jpeg: JPEG raster format (alias)
      - webp: WebP format (recommended)
  --same-dir {single}
    Write output file in same directory as source file
    with the same base name (except extension).
    Incompatible with --output-dir and --output.

  --output-dir, -d <OutputDir> {single}
    Output directory for generated images (default: doc/images).
    Incompatible with --same-dir and --output.

  --output, -o <OutputFile> {single}
    Output file path. Required when using stdin input.
    Incompatible with --same-dir and --output-dir.

  --transform-cmd, -t <TransformCmd> {single}
    Transform command to apply before generating image.
    Use %tempFile% placeholder for temporary HTML output file.
    Example: 'npx -y @markwhen/mw -o timeline -d %tempFile%'

  --viewport <Viewport> {single}
    Browser viewport size in WIDTHxHEIGHT format (e.g., 1920x1080). If not s
    pecified, the viewport is automatically sized to fit the page content.

  --quality <Quality> {single}
    Image quality for JPEG/WEBP formats, 0-100 (default: 90).

    Default value: 90
  --full-page {single}
    Capture full scrollable page height instead of viewport height.

  --wait-for-render <Milliseconds> {single}
    Extra wait time in milliseconds after page load, for JS-rendered
    content such as SPAs or web components (default: 0).
    Example: --wait-for-render 2000

    Default value: 0
  --wait-for-selector <Selector> {single}
    CSS selector to wait for before taking the screenshot.
    Useful when the target element is rendered asynchronously.
    Example: --wait-for-selector '#app'

  --inject-css <CssFile> {single}
    Path to a CSS file to inject into the page before screenshot.
    Useful to override styles, hide elements, or apply custom theme.
    Example: --inject-css custom.css

  --hide-selector <Selector> {single}

    CSS selector: the last matching element will be hidden before screenshot.
    Useful to remove floating toolbars or overlays from the captured image.
    Example: --hide-selector '#timeline > div.fixed'

  --file-filter <Regex> {single}
    Only process files matching the regular expression

    Example: --file-filter '(\.html|\.htm)$'

    Default value: (\.html|\.htm)$


DESCRIPTION:
Converts HTML files to images (PNG, JPEG, WEBP) using Puppeteer. Supports tr
ansform commands to generate HTML from other formats (e.g., Markwhen).
Can process files from git repository, specified files, or stdin.

USAGE EXAMPLES:

# Convert HTML files from git repository


html2image --format webp --same-dir


# Convert specific HTML file


html2image --format webp --same-dir file.html


# Convert Markwhen file with transform


html2image --format webp --same-dir \
  --transform-cmd 'npx -y @markwhen/mw -o timeline -d %tempFile%' \
  file.mwh


# Convert from stdin


echo "<html><body>Hello</body></html>" | \
  html2image --format png --output output.png


# Convert with custom css injection


html2image --format webp --same-dir \
  --transform-cmd 'npx -y @markwhen/mw -o timeline -d %tempFile%' \
  --inject-css src/_binaries/html2image/tests/test-markwhen.css \
  src/_binaries/html2image/tests/test-markwhen.mwh


CHANGELOG:

Version 1.0.1 (2026-05-16):

  - Fix: handle same-directory output with stdin input correctly

Version 1.0 (2026-04-24):

  - Initial version   - Support for PNG, JPEG, WEBP formats
  - Transform command support with %tempFile% placeholder
  - Stdin input support   - Configurable viewport size
  - CI mode with extension checking

VERSION: 1.0.1

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/html2image/html2image-binary.yaml

LICENSE: MIT License
Copyright (c) 2026-now François Chastanet