macros

This repository contains LaTeX macros for mathematical notation used in statistical and regression modeling, originally from the rme repository.

Contents

• macros.qmd: LaTeX macro definitions for use in Quarto documents

These macros provide convenient shorthand for common mathematical expressions used in:

• Probability and statistics
• Regression models (linear, logistic, Poisson, survival analysis)
• Maximum likelihood estimation
• Mathematical notation (vectors, matrices, derivatives, etc.)

Using as a Git Submodule

Adding the submodule to your project

From the root of your project repository, run:

git submodule add https://github.com/d-morrison/macros.git macros
git commit -m "Add macros submodule"

This will clone the macros repository into a macros/ subdirectory and record it as a submodule.

Cloning a project that already uses this submodule

When cloning a repository that includes this submodule, initialize and fetch the submodule content with:

git clone --recurse-submodules <your-repo-url>

Or, if you have already cloned the repository without --recurse-submodules:

git submodule update --init

Updating the submodule

To pull the latest changes from this repository into your project:

git submodule update --remote macros
git commit -m "Update macros submodule"

Including the macros in a Quarto document

There are two main strategies for loading these macros into Quarto output:

• include-in-header (recommended for PDF and Quarto books): Inserts the macro file into the document header. For LaTeX/PDF, use macros.qmd — definitions go into the preamble and macros work (see note below regarding \v). For HTML/RevealJS, use macros-header.html (provided in this repo), which is a loader script that reads macros.qmd and sets MathJax.tex.macros. Configure once in _quarto.yml to apply project-wide. If you use this loader approach in a website, publish macros.qmd as a static resource so the loader can fetch it at runtime.
• include shortcode (convenient for single documents): Processes and embeds the macro file inline at the point of insertion. No YAML changes required, but must be added to each .qmd file individually.

Tip: Using \providecommand instead of \newcommand in macro definitions avoids "already defined" errors when macros are included in multiple files (e.g., in a Quarto book where each chapter is a separate .qmd). The macros in this repository follow this convention.

Via include-in-header

In your Quarto document's YAML front matter, reference the appropriate header file using include-in-header or via _quarto.yml:

---
format:
  html:
    include-in-header:
      - macros/macros-header.html   # MathJax macro config script
  pdf:
    include-in-header:
      - macros/macros.qmd           # raw LaTeX goes into preamble
---

Or, in a shared _quarto.yml configuration file:

format:
  html:
    include-in-header:
      - macros/macros-header.html
  pdf:
    include-in-header:
      - macros/macros.qmd
  revealjs:
    include-in-header:
      - macros/macros-header.html

Why two files? macros.qmd remains the single source of macro definitions. For PDF, it is inserted verbatim into the LaTeX preamble. For HTML/RevealJS, macros-header.html is just a loader that reads macros.qmd and registers those same macros with MathJax.

Note on \v in PDF via include-in-header: In LaTeX/PDF output, LaTeX's font-encoding initialization restores its built-in text caron/háček accent \v at \begin{document}, overriding the preamble's \renewcommand{\v}[1]{\vecf{#1}}. For vector notation in PDF documents using include-in-header, use \vec{...} or \vecf{...} (which work across all formats and engines). If your document requires the \v shorthand specifically, add \AtBeginDocument{\renewcommand{\v}[1]{\vecf{#1}}} to your LaTeX preamble. Documents using the {{< include >}} shortcode recipe are unaffected because pandoc's macro expansion pass expands \v into \tilde during markdown processing before LaTeX compiles.

Note on \exp: macros.qmd redefines the built-in \exp to take one argument and wrap it in curly braces, so \exp{x} prints exp{x}. A bare \exp followed by a delimiter therefore breaks: \exp(x) renders as exp{(}x), and \exp\left( ... \right) fails the LaTeX compile with Missing delimiter (. inserted). Never write a bare \exp (see macros#107). Write \expf{...} for the braced form, or \expt followed by your own delimiters, such as \expt\left( ... \right) or \expt(x), for parentheses. \dexpf{...} is the derivative.

Via the Quarto include shortcode

Alternatively, you can load the macros inline using Quarto's include shortcode. Place the following block at the top of your .qmd file (after the YAML front matter):

::: {.hidden}
$$
{{< include macros/macros.qmd >}}
$$
:::

The $$...$$ delimiters cause MathJax to process the macro definitions and make them available throughout the document. The outer ::: {.hidden} div hides the block from view (Quarto's recommended approach for defining custom TeX macros).

Note for HTML output: In this repository's shortcode demo, \providecommand macros from macros.qmd (e.g., \floor) do render in HTML/RevealJS. The included macro block is processed inline before slide/body math is emitted. If you need predictable project-wide behavior across pages, use include-in-header with macros-header.html and ensure macros.qmd is published as a static resource.

This approach is useful when you prefer to load macros at the document level without modifying YAML front matter or _quarto.yml.

Note for RevealJS: placing the {{< include >}} block before the first heading creates a blank slide. In that case, prefer the include-in-header approach above. See quarto-dev discussion #8376 for details.

See also:

• quarto-dev discussion #2845 — Community discussion on strategies for including LaTeX macros from a file into a Quarto book.
• quarto-dev discussion #8376 — Follow-up discussing limitations of the include shortcode in RevealJS output and the recommended include-in-header workaround using a MathJax configuration script.
• Quarto docs: Equations — Custom TeX macros — Official Quarto documentation on defining custom TeX macros for HTML output.
• Stack Overflow: How to define LaTeX macros globally for a Quarto book? — Detailed community discussion covering both HTML and PDF strategies, including the \providecommand trick for avoiding XeTeX redefinition errors in multi-file books.