Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Markdown filters
3This file contains a collection of utility filters for dealing with
4markdown within Jinja templates.
5"""
6# Copyright (c) IPython Development Team.
7# Distributed under the terms of the Modified BSD License.
9import re
11from packaging.version import Version
13from nbconvert.utils.pandoc import get_pandoc_version
15try:
16 from .markdown_mistune import markdown2html_mistune
18except ImportError as e:
19 _mistune_import_error = e
21 def markdown2html_mistune(source: str) -> str:
22 """mistune is unavailable, raise ImportError"""
23 msg = f"markdown2html requires mistune: {_mistune_import_error}"
24 raise ImportError(msg)
27from .pandoc import convert_pandoc
29__all__ = [
30 "markdown2html",
31 "markdown2html_pandoc",
32 "markdown2html_mistune",
33 "markdown2latex",
34 "markdown2rst",
35 "markdown2asciidoc",
36]
39_MARKDOWN_FMT = "markdown+lists_without_preceding_blankline"
42def markdown2latex(source, markup=_MARKDOWN_FMT, extra_args=None):
43 """
44 Convert a markdown string to LaTeX via pandoc.
46 This function will raise an error if pandoc is not installed.
47 Any error messages generated by pandoc are printed to stderr.
49 Parameters
50 ----------
51 source : string
52 Input string, assumed to be valid markdown.
53 markup : string
54 Markup used by pandoc's reader
55 default : pandoc extended markdown
56 (see https://pandoc.org/README.html#pandocs-markdown)
58 Returns
59 -------
60 out : string
61 Output as returned by pandoc.
62 """
63 return convert_pandoc(source, markup, "latex", extra_args=extra_args)
66def markdown2html_pandoc(source, extra_args=None):
67 """
68 Convert a markdown string to HTML via pandoc.
69 """
70 extra_args = extra_args or ["--mathjax"]
71 return convert_pandoc(source, _MARKDOWN_FMT, "html", extra_args=extra_args)
74def markdown2asciidoc(source, extra_args=None):
75 """Convert a markdown string to asciidoc via pandoc"""
77 # Prior to version 3.0, pandoc supported the --atx-headers flag.
78 # For later versions, we must instead pass --markdown-headings=atx.
79 # See https://pandoc.org/releases.html#pandoc-3.0-2023-01-18
80 atx_args = ["--atx-headers"]
81 pandoc_version = get_pandoc_version()
82 if pandoc_version and Version(pandoc_version) >= Version("3.0"):
83 atx_args = ["--markdown-headings=atx"]
85 extra_args = extra_args or atx_args
86 asciidoc = convert_pandoc(source, _MARKDOWN_FMT, "asciidoc", extra_args=extra_args)
87 # workaround for https://github.com/jgm/pandoc/issues/3068
88 if "__" in asciidoc:
89 asciidoc = re.sub(r"\b__([\w \n-]+)__([:,.\n\)])", r"_\1_\2", asciidoc)
90 # urls / links:
91 asciidoc = re.sub(r"\(__([\w\/-:\.]+)__\)", r"(_\1_)", asciidoc)
93 return asciidoc
96# The mistune renderer is the default, because it's simple to depend on it
97markdown2html = markdown2html_mistune
100def markdown2rst(source, extra_args=None):
101 """
102 Convert a markdown string to ReST via pandoc.
104 This function will raise an error if pandoc is not installed.
105 Any error messages generated by pandoc are printed to stderr.
107 Parameters
108 ----------
109 source : string
110 Input string, assumed to be valid markdown.
112 Returns
113 -------
114 out : string
115 Output as returned by pandoc.
116 """
117 return convert_pandoc(source, _MARKDOWN_FMT, "rst", extra_args=extra_args)