From: Zack M. Davis Date: Wed, 15 Jul 2026 02:19:11 +0000 (-0700) Subject: formatting fidelity review X-Git-Url: https://zackmdavis.net/blog/source?a=commitdiff_plain;h=64abd5e50286de549b74012cfa434e6695d09bfd;p=An_Algorithmic_Lucidity.git formatting fidelity review --- 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 `