Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: fix markdown parsing issue with underscores in link attributes and italic text #76

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: fix markdown parsing issue with underscores in link attributes and italic text #76

wants to merge 2 commits into from

Commits on Nov 16, 2024

  1. docs: close open parenthesis around Log4j CVE's 

    In the 'Larger Cases Face Increased Leak Risk' example within docs/howto/coordination/maintaining_secrecy.md
    @codytubbs
    codytubbs authored Nov 16, 2024
    Configuration menu
    Copy the full SHA
    983ac25 View commit details
    Browse the repository at this point in the history

  2. docs: fix markdown parsing issue with underscores in link attributes … 

    …and italic text

The `python-markdown` parser (via `md_in_html` extension) incorrectly handles underscores when a `{:target="_blank"}` attribute is combined with markdown italic text on the same line.

## Current Behavior
In `docs/why_this_guide.md`, lines containing both link attributes and italic text are parsed incorrectly:

```markdown
In [VU#425163](https://kb.cert.org/vuls/id/425163){:target="_blank"} _Machine learning classifiers ..._
```
Generates incorrect HTML:
```html
<p>In <a href="https://kb.cert.org/vuls/id/425163"><abbr title="CERT Vulnerability Note">VU#</abbr>425163</a>{:target="<em>blank"} _Machine learning classifiers trained via gradient descent are vulnerable to arbitrary misclassification attack</em>,
```

## Root Cause
The `md_in_html` extension (enabled in `mkdocs.yml`) appears to misinterpret the underscore in `_blank` as a markdown italic marker when it appears before other italic text.

## Solution
Escape the underscore in `_blank` when on the same line as italic text.
```markdown
{:target="\_blank"}
```

## Testing
Parsing comparison available at: https://babelmark.github.io/?text=In+%5BVU%23425163%5D(https%3A%2F%2Fkb.cert.org%2Fvuls%2Fid%2F425163)%7B%3Atarget%3D%22%5C_blank%22%7D+_Machine+learning_%2C%0A%0AIn+%5BVU%23425163%5D(https%3A%2F%2Fkb.cert.org%2Fvuls%2Fid%2F425163)%7B%3Atarget%3D%22_blank%22%7D+_Machine+learning_%2C
note: scroll down to section 2 to view results from `python-markdown`

## Related Configuration
This issue involves the `md_in_html` extension listed under `markdown_extensions` in `mkdocs.yml`, which is likely related to the `mkdocs-material*` requirements.
    @codytubbs
    codytubbs authored Nov 16, 2024
    Configuration menu
    Copy the full SHA
    b472204 View commit details
    Browse the repository at this point in the history