aligned or align?
Beware: aligned environments in Quarto documents work differently in PDF (LaTeX) and HTML rendering. This post explains why.
The Golden Rule: Avoid Nesting Display Math
The core issue lies in LaTeX’s strictness: you cannot put one display math environment inside another (e.g., align inside equation or $$...$$). Confusingly, you can with HTML Jax rendering.
| Environment Type | Examples | Use Case |
|---|---|---|
| Display Math | \begin{equation}, \begin{align}, $$...$$ |
These must be used as standalone blocks. |
| Inner Math | \begin{aligned}, \begin{gathered} |
These are designed to be nested inside another math environment. |
Correct Usage for Aligned Equations
| Goal | Environment | Numbered? | Correct Syntax |
|---|---|---|---|
| Standalone Aligned Block | \begin{align*} |
No | Use directly, with no surrounding $$ or \[\] delimiters. |
| Numbered Aligned Block | \begin{align} |
Yes | Use directly, with no surrounding $$ or \[\] delimiters. |
Alignment Inside equation |
\begin{aligned} |
No (but outer equation is numbered) |
Use inside \begin{equation} ... \end{equation}. |
Key Takeaway: For unnumbered aligned equations, use \begin{align*} ... \end{align*} directly. This is the universally correct syntax that works for both HTML (using MathJax/KaTeX) and PDF (using LaTeX).
Stars
The asterisk versions, like \begin{align*} ... \end{align*}, are the correct way to produce unnumbered aligned equations in both Quarto PDF and HTML output.
The * versions of math environments in LaTeX suppress the automatic equation numbering.
Summary of Correct Usage
| Goal | Environment | Numbered? | Where to Use |
|---|---|---|---|
| Standalone Aligned Block | \begin{align} or \begin{align*} |
Numbered or Unnumbered | Directly in your markdown, with no surrounding $$ or \[\]. |
Aligned Block Inside equation |
\begin{aligned} or \begin{aligned*} |
Unnumbered (but outer equation is numbered) |
Nested inside a different display math environment. |
Since aligned is an inner environment and doesn’t number its lines anyway, aligned and aligned* are functionally the same but the star version may not be supported. Do not use it!. You would use them inside a container if you wanted to group the lines but avoid the nesting error.