Lalgorithms

Conversion Workflow

4 min read

This documents the workflow used to convert the LaTeX methods notes into Quartz chapter notes, plus a debrief of what was required in practice.

Parent map: index

Conversion debrief

What was completed in this pass:

  • Built a full chapter map in content/methods-rolodex/ with numbered notes: Chapter 01-07 plus Chapter 99 appendix.
  • Added a high-fidelity appendix conversion and positioned it as Chapter 99 so it sits at the bottom of the chapter map.
  • Migrated RL notes from external Quarto source (.qmd) into Chapter 07 Markdown while stripping Quarto-only wrappers.
  • Copied figures recursively into content/methods-rolodex/assets/ so existing chapter image paths render without per-image path rewrites.
  • Extended Quartz math macro aliases in quartz.config.ts to handle chapter-specific macro variants (\cov, \var, \Lagr, color/debug macros, etc.).
  • Repaired conversion fallout in large chapters: malformed tables, broken display math blocks, malformed TeX fragments, and stray citation artifacts.
  • Instituted render-first QA: build, inspect generated HTML for KaTeX red spans, patch aliases/content, and repeat until clean.
  • Completed a cross-chapter typo and notation cleanup pass, including a few substantive formula/sign fixes where conversion introduced errors.

Observed recurring breakage classes:

  • Inline/display delimiter mismatch ($$ on mixed lines, TeX \( \[ delimiters from source).
  • Pandoc/Quarto artifacts (::: blocks, orphaned ids, broken table rows).
  • Missing macro aliases causing red KaTeX output.
  • Image paths that look valid in source tree but fail in Quartz output unless assets are copied into note-local tree.

Scope and goals

  • Preserve chapter-level fidelity from source TeX.
  • Ensure Quartz renders math, links, images, and diagrams correctly.
  • Keep each chapter usable as a standalone long-form note.
  • Keep chapter numbering and index ordering stable.

1. Source inventory and chapter mapping

For each source chapter file (tex/*.tex):

  1. Record section/subsection structure.
  2. Identify figures used by the chapter (\\includegraphics).
  3. Decide destination note path under content/methods-rolodex/.
  4. Apply chapter numbering in frontmatter titles (Chapter 01, Chapter 02, …).

Typical shell checks:

wc -l tex/<chapter>.tex
rg -n '^\\section|^\\subsection|^\\subsubsection|^\\paragraph' tex/<chapter>.tex
rg -n '\\includegraphics' tex/<chapter>.tex

2. Asset migration

Copy all chapter figure assets into:

  • content/methods-rolodex/assets/

Use chapter-local asset references (./assets/...) inside the note.

3. Chapter conversion method

Current approach is hybrid, chosen per chapter complexity:

  1. Manual high-fidelity rewrite for chapters where notation cleanup is manageable.
  2. Pandoc-first conversion for very large chapters (to retain source breadth), followed by cleanup.

Pandoc path used for large chapters:

pandoc tex/<chapter>.tex -f latex -t markdown --wrap=none -o /tmp/<chapter>.md

Post-processing steps:

  • remove heading IDs,
  • strip raw div wrappers (::: blocks) if present,
  • strip Pandoc cross-reference residue (reference-type=..., []{#...}),
  • remove TeX page-break commands,
  • rewrite figure paths figs/... → ./assets/...,
  • remove unresolved citation markers where needed,
  • add chapter frontmatter and local links.

4. Math rendering compatibility

Quartz LaTeX plugin is configured with a shared customMacros dictionary in quartz.config.ts so chapter macros from the TeX source render properly.

This avoids per-chapter manual rewriting of every macro expression and improves fidelity for large converted notes.

In practice, keep extending aliases as new chapters surface macro variants (common examples: lowercase \cov, \var, and color/debug macros like \red/\txc).

5. Rolodex indexing conventions

content/methods-rolodex/index.md is maintained as the chapter map.

Current pattern:

  • numbered chapter links in sequence,
  • separate link to this workflow note,
  • related cross-links to existing site notes.

6. Quality checks per chapter

Required checks after each chapter conversion:

  1. No unsupported inline/display delimiters (\(, \), \[, \]) in final note.
  2. Quartz build succeeds.
  3. Generated HTML page exists in public/methods-rolodex/.
  4. Referenced assets exist and resolve.
  5. New note appears in search, backlinks, and graph.
  6. Built HTML has no KaTeX red-error macro text.

Typical checks:

rg -n '\\\(|\\\)|\\\[|\\\]' content/methods-rolodex/<chapter>.md
npx quartz build
ls public/methods-rolodex
ls public/methods-rolodex/assets
rg -n -F 'style="color:#cc0000;"' public/methods-rolodex/<chapter>.html
rg -o 'color:#cc0000;">\\[A-Za-z]+' public/**/*.html | sed -E 's/.*(\\[A-Za-z]+)$/\1/' | sort -u

7. Render-debug loop (new)

After each build, explicitly trawl rendered HTML for broken macros rather than relying only on source-file scans.

Workflow:

  1. Build with npx quartz build.
  2. Search chapter HTML for red KaTeX fragments (style="color:#cc0000;").
  3. Extract offending macro names (for example \red, \Real, \diag, \prodin).
  4. Add/patch aliases in quartz.config.ts (customMacros) with safe definitions.
  5. Rebuild and repeat until no red macro artifacts remain.

Notes:

  • If a macro is purely stylistic from TeX (color/highlight), patch it to no-op identity output.
  • Prefer fixing aliases globally over one-off chapter edits unless expression semantics differ.
  • Keep chapter content fidelity high; only rewrite equation text when aliases cannot safely represent original intent.

8. Current status and handoff

Current baseline after conversion:

  • numbered title,
  • chapter metadata/tags,
  • local assets,
  • functional math,
  • stable internal links.

Recommended follow-on pass (optional):

  • break chapters into concept-level notes,
  • increase cross-note linkage density,
  • reduce repeated text,
  • improve graph modularity while preserving chapter map pages.

Graph View

Backlinks