From 64abd5e50286de549b74012cfa434e6695d09bfd Mon Sep 17 00:00:00 2001 From: "Zack M. Davis" Date: Tue, 14 Jul 2026 19:19:11 -0700 Subject: [PATCH] formatting fidelity review --- CLAUDE.md | 21 +++++++++++++++++++ content/2013/app-academy-diary-week-four.md | 2 +- .../2013/lyrics-to-the-song-about-my-hair.md | 4 ++-- .../lyrics-to-the-song-about-truthseekers.md | 12 +++++------ content/2014/clarity-of-intent.md | 2 +- content/2014/defect.md | 1 + content/2014/pumpkin-spice.md | 4 ++-- content/2015/back-from-running.md | 2 +- content/2015/epistolary.md | 2 +- content/2016/0x1f431-cat-face.md | 2 +- content/2016/joined.md | 4 ++-- content/2016/oral-tradition-i.md | 2 +- content/2016/rustconf-2016-travelogue.md | 6 +++--- ...e-excuse-for-a-rustconf-2017-travelogue.md | 2 +- content/2017/sworn-to-the-word.md | 1 + ...ition-at-san-francisco-state-university.md | 8 +++---- ...putnam-competition-team-a-retrospective.md | 4 ++-- pelicanconf.py | 17 +++++++++++++++ 18 files changed, 68 insertions(+), 28 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2a96637 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,21 @@ +# An Algorithmic Lucidity + +Pelican static-site conversion of a WordPress blog (zackmdavis.net/blog). Content lives in `content/`, one Markdown file per post/page. `analgorithmiclucidity.WordPress.*.xml` is the original WXR export, used as ground truth when cross-checking whether the WordPress→Markdown conversion silently lost or corrupted formatting. + +## Known gotchas + +### Bare `$` math delimiter collides with currency amounts + +We use the `pelican-render-math` plugin (`PLUGINS = ['render_math']` in `pelicanconf.py`) for MathJax. Its inline-math regex is hardcoded to bare `$...$` with **no way to disable it** (source: `.venv/lib/python3.12/site-packages/pelican/plugins/render_math/pelican_mathjax_markdown_extension.py`). If a paragraph contains two or more literal `$` (e.g. two dollar amounts), they can pair up and get swallowed into a bogus math span, corrupting the render. Backslash-escaping (`\$`) does *not* help — the plugin's pattern runs at higher Markdown inline-pattern priority (185) than the `escape` pattern (180) specifically so real LaTeX commands survive, which as a side effect means it never sees escape sequences at all. + +Current fix, applied case-by-case as encountered: replace one or more of the conflicting `$` with the HTML entity `$` (bypasses the regex entirely since it isn't a literal `$` character in the raw source). Confirmed no other post in the corpus has this problem as of 2026-07-14 (see `content/2016/joined.md` for the one confirmed instance). + +**If this keeps recurring and the per-instance entity patching becomes annoying**: the real fix is switching to the `python-markdown-math` package (`mdx_math`) instead, configured with `enable_dollar_delimiter: False` (that's the default). Unlike `pelican-render-math`, it makes bare `$` a plain, forever-ordinary character and requires `\(...\)` for inline math instead — which is also MathJax's own actual default behavior (bare `$` inline math is opt-in upstream, precisely to avoid currency collisions; this Pelican plugin skipped that safety rail). Confirmed via its source (`enable_dollar_delimiter` default `False`, pattern priority 185, same escape-priority trick). + +Migration cost if we ever do this: (1) swap the plugin and reimplement the "only inject the MathJax `