mitmproxy / mitmproxy/pdoc

Markdown emphasis captures before math does

Open
#639 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug upstream
Dominant language
Python
Stars
2.5k
Forks
228
PR merge metrics
No merged PRs in 30d

Description

Problem Description

Pdoc appears to keep looking for markdown emphasis tokens * within both inline $...$ and display $$...$$ math. This make starred environments break Pdoc's math rendering, and leads to unrendered math if matched stars do not have surrounding whitespace.

Steps to reproduce the behavior:

For example, this fails to render, and instead produces bare text, missing the stars *, and with emphasized text between the stars. Removing the stars allows this to render correctly as displaymath. VSCode's markdown preview renders both correctly.

$$
\begin{align*}
f(x) &= x^2\\
     &= x \cdot x
\end{align*}
$$

Underscores don't seem to have the same issue, and math renders correctly if there is whitespace around the stars (but that creates other errors in the math renderer, so it can't fix the above issue).

Possibly related, but newlines within displaymath break math rendering, and math newlines \\ are ignored.

System Information

pdoc: 14.1.0
Python: 3.10.12
Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with the provided display-math snippet on pdoc 14.1.0, then trace the Markdown emphasis and inline/display math parsing paths. Done means starred LaTeX environments and multiline display math render correctly without losing or applying emphasis to math content, with regression coverage for the reported example.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.