Skip to content

Commit

Permalink
Improve markdown rendering (#4688)
Browse files Browse the repository at this point in the history
  • Loading branch information
@philippjfr
philippjfr authored Apr 25, 2023
1 parent 179aa16 commit e400fad
Show file tree
Hide file tree
Showing 16 changed files with 253 additions and 127 deletions.
34 changes: 31 additions & 3 deletions examples/reference/panes/Markdown.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@
"\n",
"* **``dedent``** (bool): Whether to dedent common whitespace across all lines.\n",
"* **``disable_math``** (boolean, `default=False`): Whether to disable MathJax math rendering for strings escaped with $$ delimiters.\n",
"* **``extensions``** (list): A list of [Python-Markdown extensions](https://python-markdown.github.io/extensions/) to use.\n",
"* **``object``** (str or object): A string containing Markdown, or an object with a ``_repr_markdown_`` method\n",
"* **``style``** (dict): Dictionary specifying CSS styles\n",
"* **``extensions``** (list): A list of [Python-Markdown extensions](https://python-markdown.github.io/extensions/) to use (does not apply for 'markdown-it' and 'myst' renderers).\n",
"* **``object``** (str or object): A string containing Markdown, or an object with a ``_repr_markdown_`` method.\n",
"* **``plugins``** (function): A list of additional markdown-it-py plugins to apply.\n",
"* **``renderer``** (literal: `'markdown-it'`, `'markdown'`, `'myst'`): Markdown renderer implementation.\n",
"\n",
"___"
]
Expand Down Expand Up @@ -182,6 +183,33 @@
"\"\"\", stylesheets=[css])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Renderer\n",
"\n",
"Since the 1.0 release Panel uses `markdown-it` as the the default markdown renderer. If you want to restore the previous default `'markdown'` or switch to `MyST` flavored Markdown you can set it via the `renderer` parameter. As an example here we render a task list using 'markdown-it' and 'markdown':"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"tasklist = \"\"\"\n",
"- [ ] Eggs\n",
"- [x] Flour\n",
"- [x] Milk\n",
"\"\"\"\n",
"\n",
"pn.Row(\n",
" pn.pane.Markdown(tasklist, renderer='markdown-it'),\n",
" pn.pane.Markdown(tasklist, renderer='markdown')\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down
195 changes: 114 additions & 81 deletions panel/dist/css/markdown.css
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,122 @@
.codehilite .hll { background-color: #2C3B41 }
.codehilite { background: var(--code-bg-color); }
.codehilite .c { color: #546E7A; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF5370 } /* Error */
.codehilite .esc { color: #89DDFF; } /* Escape */
.codehilite .g { color: #EFFFFF; } /* Generic */
.codehilite .k { color: #BB80B3; font-weight: bold } /* Keyword */
.codehilite .l { color: #C3E88D; font-weight: bold } /* Literal */
.codehilite .n { color: #EEFFFF; } /* Name */
.codehilite .o { color: #89DDFF; } /* Operator */
.codehilite .p { color: #89DDFF; } /* Punctuation */
.codehilite .ch { color: #546E7A; font-style: italic } /* Comment.Hashbang */
.codehilite .cm { color: #546E7A; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #546E7A } /* Comment.Preproc */
.codehilite .cpf { color: #546E7A; font-style: italic } /* Comment.PreprocFile */
.codehilite .c1 { color: #546E7A; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #546E7A; font-style: italic } /* Comment.Special */
.codehilite .gd { color: #FF5370; } /* Generic.Deleted */
.codehilite .ge { color: #89DDFF; font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF5370; } /* Generic.Error */
.codehilite .gh { color: #C3E88D; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #C3E88D; } /* Generic.Inserted */
.codehilite .go { color: #546E7A; } /* Generic.Output */
.codehilite .gp { color: #FFCB6B; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { color: #FF5370; font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #89DDFF; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #FF5370 } /* Generic.Traceback */
.codehilite .kc { color: #89DDFF; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #BB80B3; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #89DDFF; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #89DDFF } /* Keyword.Pseudo */
.codehilite .kr { color: #BB80B3; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #BB80B3 } /* Keyword.Type */
.codehilite .ld { color: #C3E88D } /* Literal.Date */
.codehilite .m { color: #F78C6C } /* Literal.Number */
.codehilite .s { color: #C3E88D } /* Literal.String */
.codehilite .na { color: #BB80B3 } /* Name.Attribute */
.codehilite .nb { color: #82AAFF } /* Name.Builtin */
.codehilite .nc { color: #FFCB6B; font-weight: bold } /* Name.Class */
.codehilite .no { color: #EEFFFF } /* Name.Constant */
.codehilite .nd { color: #82AAFF } /* Name.Decorator */
.codehilite .ni { color: #89DDFF; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #FFCB6B; font-weight: bold } /* Name.Exception */
.codehilite .nf { color: #82AAFF } /* Name.Function */
.codehilite .nl { color: #82AAFF } /* Name.Label */
.codehilite .nn { color: #FFCB6B; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #FF5370; font-weight: bold } /* Name.Tag */
.codehilite .np { color: #FFCB6B; } /* Name.Property */
.codehilite .nx { color: #EFFFFF; } /* Name.Other */
.codehilite .nv { color: #89DDFF; } /* Name.Variable */
.codehilite .ow { color: #89DDFF; font-weight: bold } /* Operator.Word */
.codehilite .pm { color: #89DDFF; } /* Punctuation.Marker */
.codehilite .py { color: #FFCB6B; } /* Name.Property */
.codehilite .w { color: #EEFFFF } /* Text.Whitespace */
.codehilite .mb { color: #F78C6C } /* Literal.Number.Bin */
.codehilite .mf { color: #F78C6C } /* Literal.Number.Float */
.codehilite .mh { color: #F78C6C } /* Literal.Number.Hex */
.codehilite .mi { color: #F78C6C } /* Literal.Number.Integer */
.codehilite .mo { color: #F78C6C } /* Literal.Number.Oct */
.codehilite .sa { color: #BB80B3 } /* Literal.String.Affix */
.codehilite .sb { color: #C3E88D } /* Literal.String.Backtick */
.codehilite .sc { color: #C3E88D } /* Literal.String.Char */
.codehilite .dl { color: #EEFFFF } /* Literal.String.Delimiter */
.codehilite .sd { color: #546E7A; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #C3E88D } /* Literal.String.Double */
.codehilite .se { color: #EEFFFF; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #C3E88D } /* Literal.String.Heredoc */
.codehilite .si { color: #89DDFF; font-weight: bold } /* Literal.String.Interpol */
.codehilite .sx { color: #C3E88D } /* Literal.String.Other */
.codehilite .sr { color: #89DDFF } /* Literal.String.Regex */
.codehilite .s1 { color: #C3E88D } /* Literal.String.Single */
.codehilite .ss { color: #89DDFF } /* Literal.String.Symbol */
.codehilite .bp { color: #89DDFF } /* Name.Builtin.Pseudo */
.codehilite .fm { color: #82AAFF } /* Name.Function.Magic */
.codehilite .vc { color: #89DDFF } /* Name.Variable.Class */
.codehilite .vg { color: #89DDFF } /* Name.Variable.Global */
.codehilite .vi { color: #89DDFF } /* Name.Variable.Instance */
.codehilite .vm { color: #82AAFF } /* Name.Variable.Magic */
.codehilite .il { color: #F78C6C } /* Literal.Number.Integer.Long */

.codehilite .hll { background-color: #ffffcc }
.codehilite { background: #f8f8f8; }
.codehilite .c { color: #408080; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF0000 } /* Error */
.codehilite .k { color: #008000; font-weight: bold } /* Keyword */
.codehilite .o { color: #666666 } /* Operator */
.codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */
.codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #BC7A00 } /* Comment.Preproc */
.codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
.codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */
.codehilite .gd { color: #A00000 } /* Generic.Deleted */
.codehilite .ge { font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF0000 } /* Generic.Error */
.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #00A000 } /* Generic.Inserted */
.codehilite .go { color: #888888 } /* Generic.Output */
.codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #0044DD } /* Generic.Traceback */
.codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #008000 } /* Keyword.Pseudo */
.codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #B00040 } /* Keyword.Type */
.codehilite .m { color: #666666 } /* Literal.Number */
.codehilite .s { color: #BA2121 } /* Literal.String */
.codehilite .na { color: #7D9029 } /* Name.Attribute */
.codehilite .nb { color: #008000 } /* Name.Builtin */
.codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.codehilite .no { color: #880000 } /* Name.Constant */
.codehilite .nd { color: #AA22FF } /* Name.Decorator */
.codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.codehilite .nf { color: #0000FF } /* Name.Function */
.codehilite .nl { color: #A0A000 } /* Name.Label */
.codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */
.codehilite .nv { color: #19177C } /* Name.Variable */
.codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.codehilite .w { color: #bbbbbb } /* Text.Whitespace */
.codehilite .mb { color: #666666 } /* Literal.Number.Bin */
.codehilite .mf { color: #666666 } /* Literal.Number.Float */
.codehilite .mh { color: #666666 } /* Literal.Number.Hex */
.codehilite .mi { color: #666666 } /* Literal.Number.Integer */
.codehilite .mo { color: #666666 } /* Literal.Number.Oct */
.codehilite .sa { color: #BA2121 } /* Literal.String.Affix */
.codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */
.codehilite .sc { color: #BA2121 } /* Literal.String.Char */
.codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */
.codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #BA2121 } /* Literal.String.Double */
.codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */
.codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.codehilite .sx { color: #008000 } /* Literal.String.Other */
.codehilite .sr { color: #BB6688 } /* Literal.String.Regex */
.codehilite .s1 { color: #BA2121 } /* Literal.String.Single */
.codehilite .ss { color: #19177C } /* Literal.String.Symbol */
.codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */
.codehilite .fm { color: #0000FF } /* Name.Function.Magic */
.codehilite .vc { color: #19177C } /* Name.Variable.Class */
.codehilite .vg { color: #19177C } /* Name.Variable.Global */
.codehilite .vi { color: #19177C } /* Name.Variable.Instance */
.codehilite .vm { color: #19177C } /* Name.Variable.Magic */
.codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */
h1 { margin-block-start: 0.34em }
h2 { margin-block-start: 0.42em }
h3 { margin-block-start: 0.5em }
h4 { margin-block-start: 0.67em }
h5 { margin-block-start: 0.84em }
h6 { margin-block-start: 1.17em }
ul { padding-inline-start: 2em }
ol { padding-inline-start: 2em }
strong { font-weight: 600 }
a { color: var(--panel-primary-color); }
code {
color: var(--code-text-color);
}

a.header-anchor {
visibility: hidden;
}

.markdown h1 { margin-block-start: 0.34em }
.markdown h2 { margin-block-start: 0.42em }
.markdown h3 { margin-block-start: 0.5em }
.markdown h4 { margin-block-start: 0.67em }
.markdown h5 { margin-block-start: 0.84em }
.markdown h6 { margin-block-start: 1.17em }
.markdown ul { padding-inline-start: 2em }
.markdown ol { padding-inline-start: 2em }
.markdown strong { font-weight: 600 }
.markdown a { color: -webkit-link }
.markdown a { color: -moz-hyperlinkText }
h1:hover a.header-anchor::before,
h2:hover a.header-anchor::before {
content: "";
background-image: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxNi4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4Ig0KCSB3aWR0aD0iNTEycHgiIGhlaWdodD0iNTEycHgiIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBlbmFibGUtYmFja2dyb3VuZD0ibmV3IDAgMCA1MTIgNTEyIiB4bWw6c3BhY2U9InByZXNlcnZlIj4NCjxwYXRoIGZpbGw9IiM4MDgwODAiIGQ9Ik00NTkuNjU0LDIzMy4zNzNsLTkwLjUzMSw5MC41Yy00OS45NjksNTAtMTMxLjAzMSw1MC0xODEsMGMtNy44NzUtNy44NDQtMTQuMDMxLTE2LjY4OC0xOS40MzgtMjUuODEzDQoJbDQyLjA2My00Mi4wNjNjMi0yLjAxNiw0LjQ2OS0zLjE3Miw2LjgyOC00LjUzMWMyLjkwNiw5LjkzOCw3Ljk4NCwxOS4zNDQsMTUuNzk3LDI3LjE1NmMyNC45NTMsMjQuOTY5LDY1LjU2MywyNC45MzgsOTAuNSwwDQoJbDkwLjUtOTAuNWMyNC45NjktMjQuOTY5LDI0Ljk2OS02NS41NjMsMC05MC41MTZjLTI0LjkzOC0yNC45NTMtNjUuNTMxLTI0Ljk1My05MC41LDBsLTMyLjE4OCwzMi4yMTkNCgljLTI2LjEwOS0xMC4xNzItNTQuMjUtMTIuOTA2LTgxLjY0MS04Ljg5MWw2OC41NzgtNjguNTc4YzUwLTQ5Ljk4NCwxMzEuMDMxLTQ5Ljk4NCwxODEuMDMxLDANCglDNTA5LjYyMywxMDIuMzQyLDUwOS42MjMsMTgzLjM4OSw0NTkuNjU0LDIzMy4zNzN6IE0yMjAuMzI2LDM4Mi4xODZsLTMyLjIwMywzMi4yMTljLTI0Ljk1MywyNC45MzgtNjUuNTYzLDI0LjkzOC05MC41MTYsMA0KCWMtMjQuOTUzLTI0Ljk2OS0yNC45NTMtNjUuNTYzLDAtOTAuNTMxbDkwLjUxNi05MC41YzI0Ljk2OS0yNC45NjksNjUuNTQ3LTI0Ljk2OSw5MC41LDBjNy43OTcsNy43OTcsMTIuODc1LDE3LjIwMywxNS44MTMsMjcuMTI1DQoJYzIuMzc1LTEuMzc1LDQuODEzLTIuNSw2LjgxMy00LjVsNDIuMDYzLTQyLjA0N2MtNS4zNzUtOS4xNTYtMTEuNTYzLTE3Ljk2OS0xOS40MzgtMjUuODI4Yy00OS45NjktNDkuOTg0LTEzMS4wMzEtNDkuOTg0LTE4MS4wMTYsMA0KCWwtOTAuNSw5MC41Yy00OS45ODQsNTAtNDkuOTg0LDEzMS4wMzEsMCwxODEuMDMxYzQ5Ljk4NCw0OS45NjksMTMxLjAzMSw0OS45NjksMTgxLjAxNiwwbDY4LjU5NC02OC41OTQNCglDMjc0LjU2MSwzOTUuMDkyLDI0Ni40MiwzOTIuMzQyLDIyMC4zMjYsMzgyLjE4NnoiLz4NCjwvc3ZnPg0K');
background-size: 0.7em 0.7em;
background-repeat: no-repeat;
display: inline-block;
width: 0.7em;
height: 0.7em;
visibility: visible;
}

:host(.markdown) .codehilite {
.codehilite {
padding: 1rem 1.25rem;
margin-top: 1rem;
margin-bottom: 1rem;
border-radius: 0.25rem;
}

table, th, td {
border: 1px solid;
border-collapse: collapse;
padding: 5px;
}
60 changes: 55 additions & 5 deletions panel/pane/markup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -319,13 +319,22 @@ class Markdown(HTMLBasePane):

extensions = param.List(default=[
"extra", "smarty", "codehilite"], doc="""
Markdown extension to apply when transforming markup.""")
Markdown extension to apply when transforming markup.
Does not apply if renderer is set to 'markdown-it' or 'myst'.""")

plugins = param.List(default=[], doc="""
Additional markdown-it-py plugins to use.""")

renderer = param.Selector(default='markdown-it', objects=[
'markdown-it', 'myst', 'markdown'], doc="""
Markdown renderer implementation.""")

# Priority depends on the data type
priority: ClassVar[float | bool | None] = None

_rename: ClassVar[Mapping[str, str | None]] = {
'dedent': None, 'disable_math': None, 'extensions': None
'dedent': None, 'disable_math': None, 'extensions': None,
'plugins': None, 'renderer': None
}

_rerender_params: ClassVar[List[str]] = [
Expand Down Expand Up @@ -357,9 +366,50 @@ def _transform_object(self, obj: Any) -> Dict[str, Any]:
obj = obj._repr_markdown_()
if self.dedent:
obj = textwrap.dedent(obj)
html = markdown.markdown(
obj, extensions=self.extensions, output_format='html5'
)
if self.renderer == 'markdown':
html = markdown.markdown(
obj, extensions=self.extensions, output_format='html5'
)
else:
from markdown_it import MarkdownIt
from markdown_it.renderer import RendererHTML
from mdit_py_plugins.anchors import anchors_plugin
from mdit_py_plugins.deflist import deflist_plugin
from mdit_py_plugins.footnote import footnote_plugin
from mdit_py_plugins.tasklists import tasklists_plugin

def hilite(token, langname, attrs):
try:
from markdown.extensions.codehilite import CodeHilite
return CodeHilite(src=token, lang=langname).hilite()
except Exception:
return token

if self.renderer == 'markdown-it':
parser = MarkdownIt('gfm-like', renderer_cls=RendererHTML)
elif self.renderer == 'myst':
from myst_parser.parsers.mdit import (
MdParserConfig, create_md_parser,
)
config = MdParserConfig(heading_anchors=1, enable_extensions=[
'colon_fence', 'linkify', 'smartquotes', 'tasklist',
'attrs_block'
], enable_checkboxes=True)
parser = create_md_parser(config, RendererHTML)
parser = (
parser
.enable('strikethrough').enable('table')
.use(anchors_plugin, permalink=True).use(deflist_plugin).use(footnote_plugin).use(tasklists_plugin)
)
for plugin in self.plugins:
parser = parser.use(plugin)
try:
from mdit_py_emoji import emoji_plugin
parser = parser.use(emoji_plugin)
except Exception:
pass
parser.options['highlight'] = hilite
html = parser.render(obj)
return dict(object=escape(html))

def _process_param_change(self, params):
Expand Down
Loading

0 comments on commit e400fad

Please sign in to comment.