Tutorial

Creating a document with automath render doc

The automath render doc command renders an embedded document as HTML, printed to standard output.

automath render doc DOC_REF > output.html

DOC_REF is the reference of an embedded document. Support for a path to a YAML file is planned.

To list all available embedded documents:

automath show docs --all
Available embedded documents 
fr: 5e/cm1_blanche::W01a
    5e/cm1_blanche::W01b
    5e/cm1_blanche::W01c
    5e/cm1_blanche::W01d
    5e/cm1_blanche::W02a
    5e/cm1_blanche::W02b
    5e/cm1_blanche::divisions
    5e/cm1_blanche::exam
    5e/cm1_blanche::multiplications
    5e/cm1_blanche::operations_vocabulary
    6e/cm1_blanche::W01a
    6e/cm1_blanche::W01b
    6e/cm1_blanche::W01c
    6e/cm1_blanche::W01d
    6e/cm1_blanche::W02a
    6e/cm1_blanche::W02b
    6e/cm1_blanche::exam
    6e/cm1_blanche::multiplications
    6e/cm1_blanche::multiplications_hole
    6e/cm1_blanche::multiplications_reversed
    6e/cm4_verte::divisions
    6e/cm5_bleue::divisions
    6e/cm7_rouge::multiply_by_one_and_a_half
    6e/cm8_noire::multiply_by_one_or_two_and_a_half

Exporting to PDF with automath render pdf

The automath render pdf command converts an HTML file produced by automath render doc to PDF using WeasyPrint.

automath render pdf output.html

The output PDF is written next to the HTML file with a .pdf extension. For slideshow documents, per-page display durations are automatically injected into the PDF so that it can be used as a self-advancing presentation.

Using HTML slideshows

HTML slideshow files can be opened directly in a browser. For a distraction-free, full-screen experience, Chromium's --app flag removes all browser chrome:

chromium --app=file:///path/to/output.html --start-maximized

Thunar custom action — to open any .html slideshow with a double-click, add a custom action in Thunar (Edit → Configure Custom Actions):

  • Command: chromium --app=%f --start-maximized
  • File pattern: *.html
Firefox “App Mode” (like Chromium’s --app)
  1. Create a dedicated profile: launch Firefox with the -P option (for example, firefox -P). Create a new profile — you can name it “app”.
  2. Enable customization: open the new profile, type about:config in the address bar, and accept the risk warning. Search for the preference toolkit.legacyUserProfileCustomizations.stylesheets and set it to true.
  3. Create the userChrome.css file:
    • Locate the folder for your new “app” profile (you can find it via about:profiles and look for the “Root Directory”).
    • In this folder, create a subfolder named chrome (in lowercase).
    • Inside this chrome folder, create a text file named userChrome.css.
    Open this file and paste the following content into it: 
    /* Hides the tab bar */
#TabsToolbar {
  visibility: collapse !important;
}

/* Hides the navigation bar (address bar) */
#nav-bar {
  visibility: collapse !important;
}

/* Hide the menu bar */
#toolbar-menubar {
  visibility: collapse !important;
}

/* Hide the sidebar (bookmarks, history) */
#sidebar-box {
  visibility: collapse !important;
}
  4. Run your application: use the following command in the terminal, replacing /path/to/your/page.html with the path to your file. 
    firefox -P app -no-remote file:///path/to/your/page.html
    • -P app: uses the “app” profile you just configured.
    • -no-remote: opens a separate instance, independent of your regular Firefox session.

Keyboard shortcuts

Key Action
Space Start the slideshow / pause / resume
P Privacy pause: hide the current slide; press again to resume
→ Next slide (while running)
← Previous slide
R Restart the current question (reset timer)
F/F11 Toggle fullscreen
F9 Toggle preview
Esc Exit fullscreen / privacy pause / preview / help
? Show / hide this help

Rendering SVG with automath render svg

The automath render svg command renders a mathematical expression as an SVG string, printed to standard output.

automath render svg "EXPRESSION"

The produced SVG is designed to be used inline in an HTML document and is compatible with WeasyPrint.

Expression syntax

Expressions use a simple asciimath-like notation. Plain text is rendered as-is; mathematical content is introduced with keywords followed by curly braces.

Options syntax

All keywords can receive values and options. A pipe (|) separates options from values. If a keyword requires or allows several values, then they must be separated by semicolons (;). Example: frac{2; 3 | color=#3b7d25}

Text mode

Default mode is text mode, which will be rendered as is. Inside math mode, you can wrap with text{} any content that should be rendered as normal text.

Math mode

Wrap mathematical content with math{}.

The font defined by math_name and math_path in automath.yaml is used to render the characters listed in math_chars. All other characters are rendered with the text font (defined in text_name and text_path).

In math mode:

  • Hyphens and en-dashes are automatically converted to the minus sign (−), and * is converted to ×.
  • Isolated numbers will be rendered according to locale.
  • The / operator creates a fraction.
  • The ^ operator creates a superscript.

The contents of frac{}, angle{} and table{} values will be processed by default in math mode.

Examples with default settings follow.

Numbers with English locale:

Expression Renders as
math{2450} 2,450
math{80000} 80,000
math{3.141592653589793} 3.141592653589793

Numbers with French locale:

Expression Renders as
math{2450} 2450
math{80000} 80000
math{3.141592653589793} 3,141592653589793

Locale-independent examples:

Expression Renders as
math{(4x - 6)^2 = 16x^2 - 48x + 36} (4x − 6)2 = 16x2 − 48x + 36
math{1/2 + 1/6 = 2/3} 12 + 16 = 23
math{a/{b+c}} ab + c
math{text{a}/text{b + c}} ab + c
math{1/4x} 14x
math{{1/4}x} 14 x
math{1/4 x} 14 x
math{1/4+x} 14 + x
math{1/{4+x} | color=#3771c8} 14 + x
math{x^{1/2}} x12

Fractions

You can either use the / operator to create a fraction in math mode, or wrap the fraction with frac{}.

Expression Renders as
frac{2; 3 | color=#3b7d25} 23
math{2/3 | color=#3b7d25} 23
math{1/2 + frac{1; 6 | color=#b6251c} = 2/3} 12 + 16 = 23

Angle names

Wrap angle names in angle{}. The angle name is rendered by default in math mode.

English locale:

Expression Renders as
angle{ABC} ABC
angle{xOy} xOy
angle{text{xOy}} xOy

French locale:

Expression Renders as
angle{ABC} ABC
angle{xOy} xOy
angle{text{xOy}} xOy

Tables

The table{} keyword creates a table of two rows. As for the other keywords, values are separated by ;, and options follow a | separator. There must be an even number of values, the first half will be in the first row, the second half in the second row.

The table{} keyword has several options:

  • title1 and title2 set rows titles
  • borders (can be full (default) inner or none) defines the borders of data area
  • title_borders (can be full (default) inner or none) defines the borders of title column (ignored if title1 and title2 are unset)
  • col_width (can be equal (default) or auto): if equal, then all data columns share the width of the widest cell; if auto, then each data column is as wide as its widest cell.
  • row_height (can be equal (default) or auto): if equal, then both rows share the height of the tallest cell (including title cells); if auto, then each row is sized to its tallest cell.
  • baseline (can be middle (default), top or bottom): sets the vertical alignment of the table with the surrounding text. top and bottom match first and second row.
  • bubble: defines the content of the bubble (with arrow from first to second row) drawn to the right of the table. If unset (default), no bubble is drawn.
  • color: sets the color of the table data.
  • border_color: sets the color of the table borders.

English locale:

Expression Renders as
table{5 ; 10 ; 12 ; 1.25 ; 2.5 ; 3 | bubble=×text{? | color=#b6251c}} 510121.252.53× ?
table{5 ; 10 ; 12 ; 1.25 ; 2.5 ; 3 | bubble=×math{1/4 | color=#3b7d25}} 510121.252.53× 14
table{3 ; 4 ; 5 ; 9 ; 16 ; 25 | title1=Side ; title2=Area ; borders=inner ; title_borders=none ; border_color=#4d4d4d} SideArea34591625

French locale:

Expression Renders as
table{5 ; 10 ; 12 ; 1.25 ; 2.5 ; 3 | bubble=×text{? | color=#b6251c}} 510121,252,53× ?
table{5 ; 10 ; 12 ; 1.25 ; 2.5 ; 3 | bubble=×math{1/4 | color=#3b7d25}} 510121,252,53× 14

Mixed text and math

In text mode, math{}, frac{}, angle{} and table{} can be embedded in a string:

English and French locales:

Expression Renders as
The answer is: frac{2; 3 | color=#3b7d25} The answer is: 23
Is angle{ABC} an acute angle? Is ABC an acute angle?
L'angle angle{ABC} est-il aigu ? L'angle ABC est-il aigu ?
Solve this equation: math{{4x - 9}/10 = 2.7} Solve this equation: 4x − 910 = 2.7
Résoudre l'équation : math{{4x - 9}/10 = 2.7} Résoudre l'équation : 4x − 910 = 2,7
Complete this proportional table: table{3; 8; 4.5; text{? | color=#b6251c}} Complete this proportional table: 384.5?
Compléter ce tableau de proportionnalité : table{3; 8; 4.5; text{? | color=#b6251c}} Compléter ce tableau de proportionnalité : 384,5?

Limitations

Currently implemented: fractions, superscripts, angle names, tables, and mixed text/math expressions. Square roots and some composite notations (e.g. power of a power) are planned. More advanced notations (integrals, sums, limits, etc.) are not planned in the near future.