Skip to content

Improve README.md #50

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

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

Improve README.md #50

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fcae485
Improve README.md
staadecker May 31, 2025
a6f691e
Update README.md
staadecker May 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,9 @@ print("this will not be run")

Sometimes you might wish to run code blocks that depend on entities to already
be declared in the scope of the code, without explicitly declaring them. There
are currently two ways you can do this with pytest-markdown:
are currently three ways you can do this with pytest-markdown:

### Injecting global/local variables
### Method 1: Injecting global/local variables

If you have some common imports or other common variables that you want to make
use of in snippets, you can add them by creating a `pytest_markdown_docs_globals`
Expand All @@ -104,7 +104,7 @@ print(myvar, math.pi)
```
````

### Fixtures
### Method 2: Fixtures

You can use both `autouse=True` pytest fixtures in a conftest.py or named fixtures with
your markdown tests. To specify named fixtures, add `fixture:<name>` markers to the code
Expand All @@ -120,7 +120,7 @@ assert captured.out == "hello\n"

As you can see above, the fixture value will be injected as a global. For `autouse=True` fixtures, the value is only injected as a global if it's explicitly added using a `fixture:<name>` marker.

### Depending on previous snippets
### Method 3: Depending on previous snippets

If you have multiple snippets following each other and want to keep the side
effects from the previous snippets, you can do so by adding the `continuation`
Expand All @@ -136,19 +136,17 @@ assert a + " world" == "hello world"
```
````

### Compatibility with Material for MkDocs

Material for Mkdocs is not compatible with the default syntax.

But if the extension `pymdownx.superfences` is configured for mkdocs, the brace format can be used:
````markdown
```{.python continuation}
````

You will need to call pytest with the `--markdown-docs-syntax` option:
```shell
pytest --markdown-docs --markdown-docs-syntax=superfences
```
If you'd like to hide some code blocks from readers (e.g. to hide boilerplate code) you can use the [`markdown-hide-code`](https://pypi.org/project/markdown-hide-code/) extension (assuming you're using the `markdown` library or `mkdocs` to render your documentation).

> [!NOTE]
> Material for Mkdocs is not compatible with the default syntax. But if the extension `pymdownx.superfences` is [configured](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences) for mkdocs, the brace syntax can be used:
> ````markdown
> ```{.python continuation}
> ````
> You will need to call pytest with the `--markdown-docs-syntax` option:
> ```shell
> pytest --markdown-docs --markdown-docs-syntax=superfences
> ```

## MDX Comments for Metadata Options
In .mdx files, you can use MDX comments to provide additional options for code blocks. These comments should be placed immediately before the code block and take the following form:
Expand Down