From d90dce4a0a2309589b450c2a382f01e865c3723b Mon Sep 17 00:00:00 2001 From: rui-zju <12245039@zju.edu.cn> Date: Fri, 9 Oct 2026 11:38:42 +0800 Subject: [PATCH 1/2] docs: clarify file variable options in Python and CLI usage --- CHANGES.md | 1 + README.md | 14 ++++++++++++++ lib/markdown2.py | 6 ++++-- 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 8911b5cb..b7a7dc8d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,7 @@ ## python-markdown2 2.5.6 (not yet released) +- Clarify how to enable file variables in the Python API and command-line help (#269, #365). - [pull #730] Fix `tables` extra splitting multi-backtick code spans at a leading pipe and merging cells after a code span containing literal backticks. - [pull #729] Fix `tables` extra merging cells when a pipe directly follows a code span, as in compact rows like `|`-v`|verbose|`. - [pull #725] Fix `tables` extra dropping escaped pipes at the end of header and body rows. diff --git a/README.md b/README.md index 59539f63..7510fa8b 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,20 @@ This flag takes no value; file variables are ignored by default. $ markdown2 --use-file-vars foo.md > foo.html ``` +In the Python API, pass `use_file_vars=True` to `markdown()`, `markdown_path()`, +or `Markdown()`: + +```python +>>> source = "\n# Heading\n" +>>> html = markdown2.markdown(source, use_file_vars=True) +>>> '

Heading

' in html +True +``` + +`use-file-vars` is a parser option, not an extra; adding it to the `extras` list +does not enable file variables. The comment must include the `-*-` markers shown +above. + See the [project wiki](https://github.com/trentm/python-markdown2/wiki), [lib/markdown2.py](https://github.com/trentm/python-markdown2/blob/master/lib/markdown2.py) docstrings and/or `python markdown2.py --help` for more details. diff --git a/lib/markdown2.py b/lib/markdown2.py index b3c29847..5f91743b 100755 --- a/lib/markdown2.py +++ b/lib/markdown2.py @@ -98,8 +98,6 @@ PHP-Markdown Extra . * toc: The returned HTML string gets a new "toc_html" attribute which is a Table of Contents for the document. (experimental) -* use-file-vars: Look for an Emacs-style markdown-extras file variable to turn - on Extras. * wiki-links: Wiki-style `[[Page Name]]` links. The generated URL and CSS class can be configured via the "base_url", "end_url", "html_class" and "build_url" options. @@ -107,6 +105,10 @@ . * wavedrom: Support for generating Wavedrom digital timing diagrams * xml: Passes one-liner processing instructions and namespaced XML tags. + +Use --use-file-vars to enable extras declared in Emacs-style file variables +(for example, ). This is a separate +parser option, not an extra. """ # Dev Notes: From 38277ce8767d3c916beb0b927a90904f2f38a3b5 Mon Sep 17 00:00:00 2001 From: rui-zju <12245039@zju.edu.cn> Date: Fri, 9 Oct 2026 17:52:05 +0800 Subject: [PATCH 2/2] docs: simplify file-variable guidance after review --- CHANGES.md | 2 +- README.md | 21 ++++----------------- lib/markdown2.py | 4 ---- 3 files changed, 5 insertions(+), 22 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index b7a7dc8d..4cd67e57 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,7 +2,7 @@ ## python-markdown2 2.5.6 (not yet released) -- Clarify how to enable file variables in the Python API and command-line help (#269, #365). +- [pull #736] Clarify how to enable file variables in the Python API and command-line help (#269, #365). - [pull #730] Fix `tables` extra splitting multi-backtick code spans at a leading pipe and merging cells after a code span containing literal backticks. - [pull #729] Fix `tables` extra merging cells when a pipe directly follows a code span, as in compact rows like `|`-v`|verbose|`. - [pull #725] Fix `tables` extra dropping escaped pipes at the end of header and body rows. diff --git a/README.md b/README.md index 7510fa8b..eeb9f109 100644 --- a/README.md +++ b/README.md @@ -72,28 +72,15 @@ I think pip-based installation will enable this as well: $ markdown2 foo.md > foo.html ``` -Use `--use-file-vars` to enable extras declared in Emacs-style file variables, -such as `` at the top of a file. -This flag takes no value; file variables are ignored by default. +Use `--use-file-vars` on the CLI, or `use_file_vars=True` with `markdown()`, +`markdown_path()` or `Markdown()`, to enable extras declared in Emacs-style +file variables such as `` at the top +of a file. This option is disabled by default and is not an extra. ```shell $ markdown2 --use-file-vars foo.md > foo.html ``` -In the Python API, pass `use_file_vars=True` to `markdown()`, `markdown_path()`, -or `Markdown()`: - -```python ->>> source = "\n# Heading\n" ->>> html = markdown2.markdown(source, use_file_vars=True) ->>> '

Heading

' in html -True -``` - -`use-file-vars` is a parser option, not an extra; adding it to the `extras` list -does not enable file variables. The comment must include the `-*-` markers shown -above. - See the [project wiki](https://github.com/trentm/python-markdown2/wiki), [lib/markdown2.py](https://github.com/trentm/python-markdown2/blob/master/lib/markdown2.py) docstrings and/or `python markdown2.py --help` for more details. diff --git a/lib/markdown2.py b/lib/markdown2.py index 5f91743b..8f0e0a6d 100755 --- a/lib/markdown2.py +++ b/lib/markdown2.py @@ -105,10 +105,6 @@ . * wavedrom: Support for generating Wavedrom digital timing diagrams * xml: Passes one-liner processing instructions and namespaced XML tags. - -Use --use-file-vars to enable extras declared in Emacs-style file variables -(for example, ). This is a separate -parser option, not an extra. """ # Dev Notes: