# `mix expresso`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/mix/tasks/expresso.ex#L1)

Make one HTML document from a deck

    $ mix expresso <input> [output]
    $ mix expresso <input> [output] --watch [--port <port>]
    $ mix expresso <input> [output] --check[=layout | =a11y | =browser] [--size <size>]...

`<input>` is the Elixir script of the deck, or `-` for the standard input.
The script returns an `Expresso.Deck` struct, or a module that uses the DSL
of `Expresso`.

`[output]` is the file for the HTML, or `-` for the standard output. Without
it, the task writes the HTML to the standard output.

## Watch mode

With `--watch`, the task serves the document at `http://127.0.0.1:4100/`.
Open that address in a browser. After each change to the deck file, or to an
image, a diagram or a style sheet of the deck, the task renders the deck
again. The page then reloads, and it shows the same step.

With `[output]`, the task also writes the document to that file after each
good render. When a render fails, the task writes the error, and the page
keeps the last good document. The watch mode needs an input file. Stop it
with Ctrl-C.

## Check mode

With `--check`, the task renders the deck, checks it, and writes a report
to the standard output. The exit status is 1 when the report has a problem,
so a CI job can run the check. With `[output]`, the task also writes the
document to that file. Each level runs the checks of the level before it:

  * `--check` - the render, the contrast of the theme, and the text for a
    screen reader. It needs no other tool.
  * `--check=layout` - also the layout check at each step, in a headless
    Chrome or Chromium at 1920 × 1080. Give the path of the browser in
    `EXPRESSO_CHROMIUM` when the task does not find it.
  * `--check=a11y` - also the rules of axe-core at each step and in each
    view. Run `npm install --save-dev axe-core` in the directory of the
    deck, or give the path of `axe.min.js` in `EXPRESSO_AXE`.
  * `--check=browser` - also the keys of the presenter in Playwright: each
    step, each view, the focus and the errors of the script. Add the Hex
    package `playwright_ex` to your project, and run
    `npm install --save-dev playwright axe-core` and
    `npx playwright install chromium` in the directory of the deck.

A browser level checks the page at 1920 × 1080. Give `--size 1024x768` for
another size, and give the option more than one time for more sizes. Each
problem of one size only names its size.

`mix expresso --install-check-tools` installs the npm packages and the
browser of the browser levels into a directory of the user.
`docs/how-to/check-a-deck.md` tells how to install each tool.

## Options

  * `--watch` - serve the deck, and render it again after each change
  * `--port <port>` - the port for `--watch`, from 1 to 65535. The default
    is 4100.
  * `--check`, `--check=layout`, `--check=a11y`, `--check=browser` - check
    the deck, and write a report
  * `--size <width>x<height>` - a size of the page for a browser level of
    `--check`, such as `1024x768`. The default is 1920 × 1080.
  * `-h`, `--help` - show this help
  * `--version` - show the version of Expresso
  * `--install-check-tools` - install the tools of the browser levels of
    `--check`. It needs Node and npm.

Each other argument that starts with `-` is an error, and so is a third
path. A path that starts with `-` needs a directory in front of it, such as
`./-deck.exs`.

## Exit status

The task writes the usage text and each error message to the standard
error, and the exit status is then 1. With `--check`, a problem in the
report also gives the exit status 1. When the standard output closes
before the task writes all the HTML, as for `| head`, the task stops with no
message, and the exit status is 0.

---

*Consult [api-reference.md](api-reference.md) for complete listing*