demo-shortcode.qmd

---
title: "Demo: Loading Macros via include shortcode"
format:
  html: default
  pdf: default
  revealjs:
    output-file: demo-shortcode-slides.html
    scrollable: true
    center: false
  docx: default
---

{{< include macros.qmd >}}

This page demonstrates the [`include` shortcode](https://quarto.org/docs/authoring/includes.html) strategy for loading macros into a Quarto document.

The `{{< include macros.qmd >}}` shortcode at the top of this file embeds the entire contents of `macros.qmd` inline at that point. Since `macros.qmd` contains only raw LaTeX macro definitions (`\def`, `\providecommand`, etc.), Quarto passes them through as raw LaTeX for PDF output (where they are processed inline in the document body as LaTeX commands) and as math for HTML/RevealJS output (where they are processed by MathJax).

> **Note:** This demo uses `macros.qmd` directly (same directory). When using this repository as a submodule, use `macros/macros.qmd` instead.

## Example math

The table below uses macros defined with `\def` in `macros.qmd`. These macros work across all output formats:

| Description | Code | Output |
|---|---|---|
| Greek: alpha | `$\a$` | $\a$ |
| Greek: beta | `$\b$` | $\b$ |
| Greek: gamma | `$\g$` | $\g$ |
| Greek: lambda | `$\l$` | $\l$ |
| Greek: sigma | `$\s$` | $\s$ |
| Log-likelihood | `$\llik$` | $\llik$ |
| Independent | `$X \ind Y$` | $X \ind Y$ |
| IID distributed | `$X_i \siid \Normal(\m, \ss)$` | $X_i \siid \Normal(\m, \ss)$ |
| Vector: mu | `$\vm$` | $\vm$ |
| Hat beta | `$\hb$` | $\hb$ |

## Color macros

`macros.qmd` defines a one-argument macro for each of the 19 [LaTeX base colors](https://en.wikibooks.org/wiki/LaTeX/Colors#Predefined_colors) (`\red`, `\blue`, `\green`, `\orange`, …), using the `\color` switch form (`{\color{red}{#1}}`), which is supported by MathJax (HTML/RevealJS), lualatex (PDF), and pandoc's texmath parser (docx):

| Description | Code | Output |
|---|---|---|
| Red | `$\red{x}$` | $\red{x}$ |
| Blue | `$\blue{y}$` | $\blue{y}$ |
| Green | `$\green{z}$` | $\green{z}$ |
| Orange | `$\orange{\mu}$` | $\orange{\mu}$ |
| Combined | `$\red{x} + \blue{y} = \green{z}$` | $\red{x} + \blue{y} = \green{z}$ |
| Nested macros | `$X_i \sim_{\red{\ind}} \blue{\Normal}(\orange{\mu_i}, \green{\ss})$` | $X_i \sim_{\red{\ind}} \blue{\Normal}(\orange{\mu_i}, \green{\ss})$ |

> **Note (docx):** pandoc converts these equations to native Word math without warnings, but its docx writer drops the color styling, so in Word the equations render correctly in the default text color.

## `\providecommand` behavior in this shortcode demo

The macro `\floor` in `macros.qmd` is defined with `\providecommand`. Compare this with a `\def` macro:

| Macro type | Code | Output |
|---|---|---|
| `\providecommand` macro (`\floor`) | `$\floor{1.2}$` | $\floor{1.2}$ |
| `\def` macro (`\a`) | `$\a$` | $\a$ |

In this shortcode demo, both macros render in HTML/RevealJS. So in this setup, `\providecommand` from the included source is being handled correctly.

> **Note (RevealJS blank slide):** Content placed before the first `##` heading in RevealJS output becomes a blank title slide. Since the include shortcode is at the top of this file, RevealJS may show a blank slide before the first section. This is a [known limitation](https://github.com/orgs/quarto-dev/discussions/8376) of the shortcode approach for RevealJS. For RevealJS without a blank slide, use the [`include-in-header` strategy](demo-include-in-header.qmd) instead.