diff --git a/docs/contributing.md b/docs/contributing.md
index ead5145c..4103b976 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -315,10 +315,19 @@ words.
#### Code Blocks
-All code blocks should use the fenced code block style. If a code block is
-demonstrating Markdown syntax, if can be assigned the `md-render` attribute,
-and both the Markdown source and HTML output will be rendered in a nested set
-of code blocks.
+All code blocks should use the fenced code block style and indicate the
+language of the code contained in the block to ensure proper syntax
+highlighting.
+
+There are two special types of code blocks which will render output based on
+the content of the code block. See [Rendered Markdown](#rendered-markdown)
+and [Rendered Python](#rendered-python) below.
+
+##### Rendered Markdown
+
+If a code block is demonstrating Markdown syntax, it can be assigned the
+`md-render` attribute in place of the language, and both the Markdown source
+and HTML output will be rendered in a nested set of code blocks.
```` markdown
``` md-render
@@ -388,6 +397,87 @@ The above code block would render as follows:
Some *Markdown* text.
```
+##### Rendered Python
+
+If a code block is demonstrating Python code, it can be assigned the
+`py-render` attribute in place of the language, and both the Python code and
+output will be rendered in a nested set of code blocks. The language of the
+output should be specified using the `output-lang` attribute.
+
+```` markdown
+``` py-render { output-lang='html' }
+import markdown
+
+src = 'Some **Markdown** text.'
+fragment = markdown.markdown(src)
+```
+````
+
+The above code block will be rendered as follows:
+
+``` py-render { output-lang='html' }
+import markdown
+
+src = 'Some **Markdown** text.'
+fragment = markdown.markdown(src)
+```
+
+Note that the Python code is executed in an isolated environment. Therefore,
+any imports need to be made to avoid errors. However, as all `py-render`
+blocks on the same page are run within the same environment, an import only
+needs to be made once (before the first use) for all code blocks on the same
+page. Variables assigned in one block will be available in later blocks on the
+same page.
+
+```` markdown
+``` py-render { output-lang='html' }
+from justhtml import JustHTML
+
+html = JustHTML(fragment).to_html()
+```
+````
+
+Notice that in the block above, the variable `fragment` from the previous code
+block is available within this code block. However, `JustHTML` needs to be
+imported as it had not been previously.
+
+``` py-render { output-lang='html' }
+from justhtml import JustHTML
+
+html = JustHTML(fragment).to_html()
+```
+
+Each page contains it's own isolated environment. Objects defined on one page
+will not be available on another page and would need to be redefined.
+
+Output will be generated if one of three conditions are met. Whichever
+condition is encountered first (in decreasing order) is the controlling
+condition.
+
+1. If an error is raised, a traceback will be rendered in the output and
+ highlighted using Pygment's `PythonTracebackLexer` (`py3tb`).
+2. If the code writes to STDOUT (for example, it passes text to `print()`),
+ then the text sent to STDOUT will be rendered in the output and
+ highlighted using the language assigned to `output-lang`.
+3. If the last line of the code assigns a value to a variable, the value of
+ that variable will be rendered in the output and highlighted using the
+ language assigned to `output-lang`.
+
+If none of the above conditions are met, then the code block will render as
+normal without rendered output. However, the code block will have updated the
+isolated Python environment and any objects created can be referenced in
+later code blocks on the same page.
+
+If a Python code block should not have it's code executed and rendered, then
+simply assign it the `python` attribute. It will then be rendered as a normal
+Python code block. Any objects defined in standard Python code blocks
+will **not** be available to `py-render` style blocks
+
+Code blocks which contain Python Console sessions are not supported by
+`py-render`. They should be assigned `pycon` and contain the code and output
+as copied out of a Python Console session. Any objects defined in Python
+Session code blocks will **not** be available to `py-render` style blocks.
+
#### Changelog
Any commit/pull request which changes the behavior of the Markdown library in
diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md
index 6967ff08..67e8d5b7 100644
--- a/docs/extensions/code_hilite.md
+++ b/docs/extensions/code_hilite.md
@@ -262,7 +262,8 @@ markdown.markdown(some_text, extensions=['codehilite'])
To keep the code block's language in the Pygments generated HTML output, one can provide a custom Pygments formatter
that takes the `lang_str` option. For example,
-```python
+```py-render { output-lang='html' }
+import markdown
from pygments.formatters import HtmlFormatter
from markdown.extensions.codehilite import CodeHiliteExtension
@@ -285,24 +286,12 @@ some_text = '''\
print('hellow world')
'''
-markdown.markdown(
+output = markdown.markdown(
some_text,
extensions=[CodeHiliteExtension(pygments_formatter=CustomHtmlFormatter)],
)
```
-The formatter above will output the following HTML structure for a code block:
-
-```html
-
-```
-
[html formatter]: https://pygments.org/docs/formatters/#HtmlFormatter
[lexer]: https://pygments.org/docs/lexers/
[spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
diff --git a/docs/library.md b/docs/library.md
index 5ce6f722..c52cf53b 100644
--- a/docs/library.md
+++ b/docs/library.md
@@ -10,49 +10,26 @@ used by various projects to convert Markdown syntax into HTML.
## The Basics
To use markdown as a module, pass a string to the [`markdown.markdown`]
-[markdown.markdown] function.
+[markdown.markdown] function. The string must be a *Unicode* string
+(the default string type in Python).
-```python
+``` py-render { output-lang='html' }
import markdown
-html = markdown.markdown(your_text_string)
-```
-
-The string must be a *Unicode* string (the default string type in Python).
-``` python
src = 'Some **Markdown** text.'
-html = markdown.markdown(src)
+fragment = markdown.markdown(src)
```
-Python-Markdown only ever outputs an HTML fragment. Therefore, the value of
-`html` above would be:
-
-``` html
-Some Markdown text.
-```
+Python-Markdown only ever outputs an HTML fragment. If you need a complete
+HTML document, including ``, `` and `` tags, then you will
+need to pass the output of Python-Markdown into some other tool. For a
+minimal complete document, [JustHTML](https://emilstenstrom.github.io/justhtml/)
+can do that with a single line of code:
-If you need a complete HTML document, including ``, `` and
-`` tags, then you will need to pass the output of Python-Markdown into
-some other tool. For a minimal complete document,
-[JustHTML](https://emilstenstrom.github.io/justhtml/) can do that with a
-single line of code:
-
-``` python
+``` py-render { output-lang='html' }
from justhtml import JustHTML
-doc = JustHTML(html)
-```
-
-Assuming the value of `html` from above, the value returned by
-`doc.to_html()` would be the following string:
-
-``` html
-
-
-
- Some Markdown text.
-
-
+html = JustHTML(fragment).to_html()
```
For more sophisticated output, you may need to explore the use of a templating
diff --git a/mkdocs.yml b/mkdocs.yml
index 7c8fe760..389d9aa5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -157,13 +157,12 @@ markdown_extensions:
pygments_lang_class: true
- pymdownx.superfences:
custom_fences:
- - name: mermaid
- class: mermaid
- format: !!python/name:pymdownx.superfences.fence_code_format
- name: md-render
class: md-render
format: !!python/name:tools.superfences_formaters.md_render
-
+ - name: py-render
+ class: py-render
+ format: !!python/name:tools.superfences_formaters.py_render
plugins:
- search
diff --git a/pyproject.toml b/pyproject.toml
index 1cc76c1b..c7dc8ea1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -56,6 +56,7 @@ docs = [
'mkdocstrings-python==1.16.8',
'pygments==2.21.0',
'pymdown-extensions==11.0.2',
+ 'justhtml==3.11.2'
]
[project.urls]
diff --git a/tools/superfences_formaters.py b/tools/superfences_formaters.py
index 24518c8b..4d99a8df 100644
--- a/tools/superfences_formaters.py
+++ b/tools/superfences_formaters.py
@@ -7,6 +7,9 @@
import markdown
import yaml
import re
+import ast
+import sys
+from io import StringIO
from collections import OrderedDict
@@ -83,3 +86,92 @@ def md_render(src="", language="", class_name=None, options=None, md="", **kwarg
source = md.preprocessors['fenced_code_block'].highlight(text, 'markdown', options, md, **kwargs)
output = md.preprocessors['fenced_code_block'].highlight(html, 'html', result_options, md, **kwargs)
return f'{source}\n{output}
'
+
+
+class PyExecNamespace():
+ def __init__(self, globals=None, locals=None):
+ self.globals = globals or {}
+ self.locals = locals or {}
+
+ def exec(self, source):
+ """
+ Execute code in namespace.
+
+ If code outputs to stdout, that output is captured and returned.
+ If nothing it output to stdout, then the last line of code is checked
+ for a variable assignment. If one exists, then the value of that variable
+ is returned. If that fails, then `None` is returned.
+ """
+
+ # Temporarily redirect stdout
+ save_stdout = sys.stdout
+ sys.stdout = StringIO()
+
+ # Run code
+ try:
+ exec(source, self.globals, self.locals)
+ except KeyboardInterrupt:
+ sys.stdout.close()
+ sys.stdout = save_stdout
+ raise
+ except BaseException as exc:
+ sys.stdout.close()
+ sys.stdout = save_stdout
+ import traceback
+ tb = traceback.format_exception(exc, exc, exc.__traceback__.tb_next)
+ return 'traceback', '\n'.join(tb)
+
+ # Retreive anything sent to stdout and restore system default
+ out = sys.stdout.getvalue()
+ sys.stdout.close()
+ sys.stdout = save_stdout
+
+ if out:
+ # Return text sent to stdout
+ return 'stdout', out
+ else:
+ # Nothing sent to stdout. Try to get value of last variable assignment
+ target = None
+ a = ast.parse(source)
+ if a.body:
+ if isinstance(a_last := a.body[-1], ast.Assign):
+ target = ast.unparse(a_last.targets[0])
+ elif isinstance(a_last, (ast.AnnAssign, ast.AugAssign)):
+ target = ast.unparse(a_last.target)
+ if target and target in self.locals:
+ return target, self.locals[target]
+ return None, None
+
+
+def py_render(src="", language="", class_name=None, options=None, md="", **kwargs):
+ """ Render Python in a code block and output of the code in a result code block. """
+
+ if not hasattr(md, 'py_namespace'):
+ # This is the first instance of a Python render block on the page.
+ # Create namespace for this and all future blocks to run in.
+ md.py_namespace = PyExecNamespace()
+ target, result = md.py_namespace.exec(src)
+
+ # Retreive and remove output language from attrs
+ output_lang = kwargs['attrs'].pop('output-lang', '')
+
+ options = options or {}
+ if 'title' not in options:
+ options['title'] = 'Python'
+
+ source = md.preprocessors['fenced_code_block'].highlight(src, 'python', options, md, **kwargs)
+
+ if result is not None:
+ result_options = options.copy()
+ if target == 'traceback':
+ result_options['title'] = 'Error Raised'
+ output_lang = 'py3tb' # PythonTracebackLexer
+ elif target == 'stdout':
+ result_options['title'] = 'Text Written to STDOUT'
+ elif target is not None:
+ result_options['title'] = f'Value of `{target}`'
+
+ output = md.preprocessors['fenced_code_block'].highlight(result, output_lang, result_options, md, **kwargs)
+ return f'{source}\n{output}
'
+ # No result so only render source
+ return source
diff --git a/uv.lock b/uv.lock
index e83d113a..5b2abff4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -205,12 +205,22 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" },
]
+[[package]]
+name = "justhtml"
+version = "3.11.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c0/fc/fa19f7406a02a5fac3c4e59b366bb49b04687edf7da247e3da740125402b/justhtml-3.11.2.tar.gz", hash = "sha256:83329a7436620a79ebd0b7310b5e4d653fa0688cd315e7a92d2188febd0d6ab0", size = 956210, upload-time = "2026-08-27T16:25:52.69Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/cd/8c/8266010c7d05cd55e1c34f0f524bf611621871cc709d619a2cee2ad262a9/justhtml-3.11.2-py3-none-any.whl", hash = "sha256:366986de83fab5f7ab643f79ffb3ad44dbaeb63f34b6361b955930575417cdd2", size = 171841, upload-time = "2026-08-27T16:25:51.308Z" },
+]
+
[[package]]
name = "markdown"
source = { editable = "." }
[package.optional-dependencies]
docs = [
+ { name = "justhtml" },
{ name = "mdx-gh-links" },
{ name = "mkdocstrings" },
{ name = "mkdocstrings-python" },
@@ -226,6 +236,7 @@ testing = [
[package.metadata]
requires-dist = [
{ name = "coverage", marker = "extra == 'testing'" },
+ { name = "justhtml", marker = "extra == 'docs'", specifier = "==3.11.2" },
{ name = "mdx-gh-links", marker = "extra == 'docs'", specifier = "==0.4" },
{ name = "mkdocstrings", marker = "extra == 'docs'", specifier = "==1.0.6" },
{ name = "mkdocstrings-python", marker = "extra == 'docs'", specifier = "==1.16.8" },