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.

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

Additional markers like notest are not compatible with MkDocs #23

Open
RafaelWO opened this issue Mar 3, 2024 · 2 comments
Open

Additional markers like notest are not compatible with MkDocs #23

RafaelWO opened this issue Mar 3, 2024 · 2 comments

Comments

@RafaelWO
Copy link

RafaelWO commented Mar 3, 2024

Hi,

first of all, thanks for your work on this project! I was really happy when I realized that I could test the code snippets in my docs :)

Unfortunately, I noticed that specifying additional verbs like notest in a code fence, e.g.

```python notest
foobar = "baz"
```

results in detection errors of code blocks when using Material for MkDocs:

grafik

This is how it looks without `notest`

grafik

A possible workaround would be allowing users to specify notest (or fixtures) within HTML comments above the code block, e.g.

<!-- notest -->
```python
foobar = "baz"
```

If this makes sense for you, I'm happy to give it a try in a PR :)

@freider
Copy link
Collaborator

freider commented Mar 4, 2024

Oh that's unfortunate! The renderers/parsers I've previously looked at has happily accepted additional data after the language spec.

notest are not the only "info" markers - we also use them for fixture injection and continuation blocks (fixture:blah)

If it doesn't complicate the parsing code we could certainly allow for a separate "comment" syntax, maybe something like:
<!-- pmd-metadata: notest --> (good to have some sort of indicator that it is metadata.

According to this thread https://stackoverflow.com/questions/4823468/comments-in-markdown there doesn't seem to be an obvious "right" way to do comments in markdown, as some html renderers will actually render these comments as well. Some suggest abusing markdown link syntax instead. Anyway, happy to look at a PR if you can think of a clean way of implementing this :)

(I guess another option for you would be to patch mkdocs-material's parser to not break when looking at code blocks with multiple info fragments)

@avandierast
Copy link
Contributor

Hello :)

I've found another solution.
The extension PyMdown Superfences for Mkdocs has a special format using braces that can contain any arbitrary parameters: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#injecting-classes-ids-and-attributes

The only thing to do is to make this library compatible with the brace format and here is the PR: #26.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants