From 77e97fa4e4795bc7df29c299c3fc7f8fc764e0a9 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 10 Jan 2022 09:17:07 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20NEW:=20Add=20`strikethrough`=20exte?= =?UTF-8?q?nsion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it. For example, `~~strikethrough with *emphasis*~~`. Note, this extension is currently only supported for HTML output, and will generate a `myst.strikethrough` warning (since docutils does not have a native strikethrough node). --- docs/conf.py | 3 +++ docs/docutils.md | 3 +++ docs/syntax/optional.md | 20 +++++++++++++++++++ docs/syntax/syntax.md | 3 +++ myst_parser/docutils_renderer.py | 13 ++++++++++++ myst_parser/main.py | 10 ++++++++-- tests/test_renderers/fixtures/myst-config.txt | 16 +++++++++++++++ 7 files changed, 66 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f054c054..9ec14302 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,6 +85,7 @@ "smartquotes", "replacements", "linkify", + "strikethrough", "substitution", "tasklist", ] @@ -102,6 +103,8 @@ "using/reference.md": "syntax/reference.md", } +suppress_warnings = ["myst.strikethrough"] + def run_apidoc(app): """generate apidoc diff --git a/docs/docutils.md b/docs/docutils.md index 48e36697..0e5c9411 100644 --- a/docs/docutils.md +++ b/docs/docutils.md @@ -2,6 +2,9 @@ # MyST with Docutils +```{versionadded} 0.16.0 +``` + Sphinx, and thus MyST-Parser, is built on top of the [Docutils](https://docutils.sourceforge.io/docs/) package. MyST-Parser offers a renderer, parser and CLI-interface for working directly with Docutils, independent of Sphinx, as described below. diff --git a/docs/syntax/optional.md b/docs/syntax/optional.md index 03460473..605e9fe7 100644 --- a/docs/syntax/optional.md +++ b/docs/syntax/optional.md @@ -36,6 +36,7 @@ myst_enable_extensions = [ "linkify", "replacements", "smartquotes", + "strikethrough", "substitution", "tasklist", ] @@ -73,6 +74,22 @@ text | converted ``--`` | -- ``---`` | --- +(syntax/strikethough)= + +## Strikethrough + +```{versionadded} 0.17.0 +``` + +The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it. +For example, `~~strikethrough with *emphasis*~~` renders as: ~~strikethrough with *emphasis*~~. + +:::{warning} +This extension is currently only supported for HTML output, +and you will neeed to suppress the `myst.strikethrough` warning +(see [](howto/warnings)) +::: + (syntax/math)= ## Math shortcuts @@ -595,6 +612,9 @@ and are applied to markdown list items starting with `[ ]` or `[x]`: (syntax/fieldlists)= ## Field Lists +```{versionadded} 0.16.0 +``` + Field lists are mappings from field names to field bodies, based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists). diff --git a/docs/syntax/syntax.md b/docs/syntax/syntax.md index 05f5efe5..36adea90 100644 --- a/docs/syntax/syntax.md +++ b/docs/syntax/syntax.md @@ -403,6 +403,9 @@ and can be used to store information for blog posting (see [ablog's myst-parser ### Setting a title +```{versionadded} 0.17.0 +``` + If `myst_title_to_header` is set to `True`, and a `title` key is present in the front matter, then the title will be used as the document's header (parsed as Markdown. For example: diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py index 340753ea..b4011ea2 100644 --- a/myst_parser/docutils_renderer.py +++ b/myst_parser/docutils_renderer.py @@ -948,6 +948,19 @@ def render_table_row(self, token: SyntaxTreeNode) -> None: with self.current_node_context(para, append=True): self.render_children(child) + def render_s(self, token: SyntaxTreeNode) -> None: + """Render a strikethrough token.""" + # TODO strikethrough not currently directly supported in docutils + self.create_warning( + "Strikethrough is currently only supported in HTML output", + line=token_line(token, 0), + subtype="strikethrough", + append_to=self.current_node, + ) + self.current_node.append(nodes.raw("", "", format="html")) + self.render_children(token) + self.current_node.append(nodes.raw("", "", format="html")) + def render_math_inline(self, token: SyntaxTreeNode) -> None: content = token.content node = nodes.math(content, content) diff --git a/myst_parser/main.py b/myst_parser/main.py index ad50d545..508c1104 100644 --- a/myst_parser/main.py +++ b/myst_parser/main.py @@ -107,6 +107,7 @@ def check_extensions(self, attribute, value): "smartquotes", "replacements", "linkify", + "strikethrough", "substitution", "tasklist", ] @@ -242,6 +243,9 @@ def create_md_parser( ) -> MarkdownIt: """Return a Markdown parser with the required MyST configuration.""" + # TODO warn if linkify required and linkify-it-py not installed + # (currently the parse will unceremoniously except) + if config.commonmark_only: # see https://spec.commonmark.org/ md = MarkdownIt("commonmark", renderer_cls=renderer).use( @@ -252,9 +256,10 @@ def create_md_parser( if config.gfm_only: # see https://github.github.com/gfm/ - # TODO strikethrough not currently supported in docutils md = ( MarkdownIt("commonmark", renderer_cls=renderer) + # note, strikethrough currently only supported tentatively for HTML + .enable("strikethrough") .enable("table") .use(tasklists_plugin) .enable("linkify") @@ -287,7 +292,8 @@ def create_md_parser( md.enable("linkify") if md.linkify is not None: md.linkify.set({"fuzzy_link": config.linkify_fuzzy_links}) - + if "strikethrough" in config.enable_extensions: + md.enable("strikethrough") if "dollarmath" in config.enable_extensions: md.use( dollarmath_plugin, diff --git a/tests/test_renderers/fixtures/myst-config.txt b/tests/test_renderers/fixtures/myst-config.txt index 58109f9c..020623c3 100644 --- a/tests/test_renderers/fixtures/myst-config.txt +++ b/tests/test_renderers/fixtures/myst-config.txt @@ -35,6 +35,22 @@ www.example.com www.example.com . +[gfm-strikethrough] --myst-gfm-only="yes" +. +~~strike~~ +. + + + + + Strikethrough is currently only supported in HTML output [myst.strikethrough] + + + strike + + +. + [gfm-disallowed-html] --myst-gfm-only="yes" . <style> <em>