| name | inkwell-troubleshooting |
| description | Diagnose Inkwell extension failures - compile errors, missing templates, stale installs, wrong PDF output, broken cross-references, and toolchain problems. Use when a PDF compile fails, output looks wrong (missing pages, "??" references, wrong template), a new template or example doesn't appear, or brew/VSIX installation misbehaves. |
Inkwell Troubleshooting
Diagnostic workflow for the Inkwell extension (markdown → Pandoc → LaTeX → PDF). Work through the sections in order; each starts with the fastest check.
1. Reproduce outside the extension first
The extension's pipeline is mirrored by a standalone script. Always reproduce with it before touching extension code:
scripts/compile-demo.sh examples/demo-<template>.md --keep-work
- Exit 1 = pandoc failed (template syntax, frontmatter). Exit 2 = LaTeX engine failed (check the preserved workdir's
.log).
--keep-work preserves the temp dir; inspect the generated .tex, .aux, .toc, and .log there.scripts/compile-all-demos.sh compiles every demo and prints a pass/fail summary — run it after any template or compiler change.
If the script succeeds but the extension fails, the problem is extension-side: see sections 2 and 5.
2. Extension compiles the wrong thing / new template missing
The running extension loads from the installed copy, not this repo:
- Installed copies live at
~/.cursor/extensions/measure-one.inkwell-<version>/ (or ~/.vscode/extensions/). Check whether templates/<name>/ exists there.
- The extension resolves templates from three locations, ascending priority: built-in (
<extension>/templates/), global (~/.inkwell/templates/), project (.inkwell/templates/). A stale global/project copy silently shadows a newer built-in — but only if it has its own .latex wrapper.
- The Inkwell Templates output channel logs which template was resolved and why. The compile log's first lines (
[inkwell] template: ...) show the resolved directory.
- Fix: rebuild + reinstall (
npx @vscode/vsce package --no-dependencies, then cursor --install-extension inkwell-<version>.vsix --force), then Developer: Reload Window. A reload is always required — old code stays in memory.
3. Reading compile failures
- Inkwell LaTeX output channel (View → Output) has the full pandoc argv,
TEXINPUTS, engine passes, and a log excerpt. The argv can be pasted into a terminal verbatim.
Missing file: foo.sty → tlmgr install <pkg>; src/toolchain.ts has the file→package map (FILE_TO_PACKAGE) for files whose tlmgr package name differs.- Packages installed but still "not found" → stale ls-R index or root-owned TeX tree. Run
texhash; if that fails, check kpsewhich -var-value TEXMFROOT ownership (sudo chown -R "$USER" "$TEXMFROOT").
- Engine is a hard requirement from
template.json (pdflatex vs xelatex); a missing engine fails fast with an actionable message, never silently substitutes.
4. Wrong-looking output
- Only 2 pages / default styling instead of the template: the template didn't resolve — see section 2.
# headings are sections, not chapters (book templates): frontmatter must contain top-level-division: chapter; the compiler forwards it to pandoc as a CLI flag (extractTopLevelDivision in src/compiler.ts). compile-demo.sh mirrors this.- Figure refs print "??" or blank in Tufte templates: the wrappers spoof
caption/subcaption as loaded (pandoc-crossref injects them otherwise) and re-route \ltx@label inside floats (amsmath reverts the tufte class's label deferral in minipages). Both guards live in templates/tufte/tufte.latex and templates/tufte-book-vdqi/tufte-book-vdqi.latex — keep them when editing.
- Cross-refs
?? on first compile only: expected; the pipeline runs the engine twice for exactly this. If it persists, check the second engine pass actually ran in the log.
5. Installation and update problems
Refusing to load cask ... from untrusted tap → brew trust goldberg-consulting/inkwell, then retry.- Setup Workspace didn't pick up new examples: it copies into
.inkwell/examples/ only when missing, never overwrites. Delete the stale file, re-run Inkwell: Setup Workspace.
- Missing bundled content warning → the VSIX was built with an over-aggressive
.vscodeignore; examples/, guide.md, and templates/ must ship (see the annotated .vscodeignore).
- Release flow: bump
package.json, npm run verify, tag + publish a GitHub release; .github/workflows/release.yml builds the VSIX, uploads it, and bumps the Homebrew tap cask automatically.
6. Validation before declaring fixed
npm run verify
scripts/compile-all-demos.sh
Render a page to inspect visually (Ghostscript ships with MacTeX/brew):
gs -q -dNOPAUSE -dBATCH -sDEVICE=png16m -r100 -dFirstPage=1 -dLastPage=1 -o /tmp/page1.png examples/demo-<t>.pdf
