Directory paths in LaMD builds

LaMD projects declare several directory fields in _lamd.yml. They look interchangeable (slidesdir, diagramsdir, …) but each answers a different question and is resolved relative to a different anchor. Mixing them up is the usual cause of “the file was built but pandoc cannot find it” failures.

This guide documents current field semantics (as implemented in mdpp, dependencies, makefiles, and copy_web_diagrams.sh). Planned changes are described in CIP-0010: Unified Diagram Path Resolution.

Authoring uses the gpp macro \diagramsDir (set at preprocess time). Content refers to diagrams as \diagramsDir/ml/foo000, which becomes a path in generated markdown (for example ../slides/diagrams//ml/foo000.emf for PPTX).

Consumer

What it needs

Typical anchor

Inkscape / make

Build foo.emf from foo.svg

cwd when make runs (usually _lamd/)

pandoc

Open the path embedded in markdown

--resource-path plus paths relative to cwd

dependencies

List files for makefile prerequisites

Same as make (relative to cwd)

Published HTML

Browser URL for <img src="…">

Site root (url + baseurl), not the filesystem

For local builds (pptx, docx, tex, …), paths resolve from the build cwd. baseurl affects \diagramsDir only when mdpp --to html or mdpp --to ipynb.

Anchor: where is the build?

Most course/talk repos use this layout:

project/
├── _lamd/              ← maketalk / make run here (cwd)
│   ├── _lamd.yml
│   ├── talk.md
│   └── makefile        ← generated
├── slides/             ← slide HTML outputs + diagram sources
│   └── diagrams/
│       └── ml/
│           └── foo000.svg
└── _lectures/          ← published lecture HTML (posts)

Rule of thumb: paths in _lamd.yml are usually written relative to _lamd/ (the build cwd), not relative to the repository root and not relative to baseurl.

For the layout above:

slidesdir: ../slides/
diagramsdir: ../slides/diagrams/

Using ./slides/diagrams/ is wrong here: that resolves to _lamd/slides/diagrams/, which is not where SVG sources live.

Field reference

diagramsdir

Purpose: Directory containing diagram sources and converted assets (SVG, EMF, PDF, PNG) that macros reference via \diagramsDir.

Used by:

Tool

How

mdpp

Sets gpp -DdiagramsDir=… (see dual behaviour below)

dependencies

Substitutes \diagramsDir when scanning \includediagram{…}

Make (PPTXDEPS, DOCXDEPS, …)

Inkscape rules build $(DIAGRAMSDIR)/…/*.emf from .svg

copy_web_diagrams.sh

Locates source files to copy into publish trees

Dual behaviour in mdpp (lamd/mdpp.py):

url = diagramsurl or (url + baseurl)
diagrams_dir = url + diagramsdir          # when --to html or ipynb
diagrams_dir = diagramsdir              # when --to pptx, docx, tex, …
# Makefile always passes --diagrams-dir $(DIAGRAMSDIR), overriding the above

  • Local formats (pptx, docx, tex, …): \diagramsDir is the filesystem path from config (or --diagrams-dir). Must be valid from _lamd/ cwd.

  • HTML / ipynb: \diagramsDir becomes a URL prefix unless --diagrams-dir overrides it. Prefer explicit diagramsurl when the published path differs from the filesystem layout.

Not the same as: slidesdir (outputs and resource-path only), writediagramsdir (generated diagrams), or baseurl alone.

diagramsurl (optional)

Purpose: Override the URL prefix used for \diagramsDir in HTML/ipynb when url + baseurl + diagramsdir would be wrong.

Example: site at https://example.org/course/ with diagrams served at https://example.org/course/slides/diagrams/:

url: https://example.org/
baseurl: course/
diagramsurl: https://example.org/course/slides/
diagramsdir: diagrams/    # URL suffix after diagramsurl, or filesystem path for local builds

If unset, mdpp uses url + baseurl as the URL prefix.

slidesdir

Purpose: Where built slide HTML is copied (cp … ${SLIDESDIR}/…) and a root for pandoc --resource-path (with . and includes).

Used by:

Tool

How

make-slides.mk

cp ${BASE}.slides.html ${SLIDESDIR}/${OUT}.slides.html

make-talk-flags.mk

PPTXFLAGS=… --resource-path .:$(INCLUDESDIR):$(SLIDESDIR)

copy_web_diagrams.sh

Second argument pair: publish target under slides tree

Relationship to diagrams: In many projects, diagramsdir is slidesdir + diagrams/ (e.g. ../slides/ + diagrams/ → ../slides/diagrams/). That keeps diagram assets next to slide outputs. They are still separate keys with separate roles; duplicating the path in config is intentional.

Not combined with baseurl for local file lookup. baseurl does not appear in makefile diagram rules or dependencies.

writediagramsdir

Purpose: Where generated diagrams are written (e.g. manim, dynamic figures), via gpp -DwriteDiagramsDir=….

Default: . (often _lamd/ itself).

Distinct from diagramsdir: diagramsdir is for checked-in SVG/EMF assets; writediagramsdir is for outputs produced during build.

url and baseurl

Purpose: Jekyll/GitHub Pages site location for published lecture pages.

Used by:

Tool

How

mdpp

Prefix for \diagramsDir when --to html or --to ipynb (unless diagramsurl)

flags post

edit_url metadata for GitHub edit links

Not used by: pptx/docx build, inkscape conversion, or dependencies batch (local paths only).

Example from a course site:

url: "https://mlatcl.github.io/"
baseurl: mlfc/

Published pages live under https://mlatcl.github.io/mlfc/…. That is unrelated to ../slides/diagrams/ on disk except that you usually copy diagrams into the tree that GitHub Pages serves (copy_web_diagrams.sh → ${SLIDESDIR}/diagrams/).

Other output directories

Field

Role

postsdir / practicalsdir

Destination for compiled lecture/practical HTML

notesdir

PDF notes output

notebooksdir

Jupyter notebook output

snippetsdir

\include{…} search path (often absolute or $HOME/…)

bibdir

Bibliography files

macrosdir

gpp macro definitions

These do not substitute for diagramsdir.

End-to-end flow (PPTX example)

  1. Authoring: \includediagram{\diagramsDir/ml/quadratic_basis000}{…} in snippets.

  2. dependencies batch (with --diagrams-dir $(DIAGRAMSDIR)): lists ../slides/diagrams//ml/quadratic_basis000.emf as pptxdiagrams prerequisite.

  3. make-figures.mk: ../slides/diagrams//ml/quadratic_basis000.emf built from .svg via Inkscape.

  4. mdpp (--diagrams-dir ../slides/diagrams/): markdown contains ![](../slides/diagrams//ml/quadratic_basis000.emf).

  5. pandoc (--resource-path .:includes:../slides/): resolves path from _lamd/ cwd; EMF must exist at that relative path.

All five steps must agree on the same filesystem path for \diagramsDir.

Configuration checklist

When diagram paths fail, verify in order:

  1. cwd: Are you building from _lamd/ (where _lamd.yml and generated makefile live)?

  2. diagramsdir: From _lamd/, does ls $(diagramsdir)/ml/*.svg show sources?

  3. Consistency: Does dependencies batch … --diagrams-dir $(diagramsdir) list the same .emf paths that appear in *.slides.pptx.markdown?

  4. Regenerate: After changing _lamd.yml, run maketalk again so the makefile picks up new DIAGRAMSDIR / PPTXDEPS.

  5. HTML only: If slides render locally but not on the site, check url / baseurl / diagramsurl, not diagramsdir alone.