mix expresso (expresso v0.1.0)

Copy Markdown View Source

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.