markdown2dash 0.1.0a2

Markdown-2-Dash

.. toc:: :min_level: 3

Markdown-2-Dash or m2d is a standalone package forked out of the official documentation for dash-mantine-components. Some form of m2d has existed since the inception of the documentation, but I figured more people can make use of this to document their dash apps or component libraries.

Have a look here to see how this README would look after parsing with m2d.

Installation

pip install markdown2dash

poetry add markdown2dash

Quickstart

Just parse the contents of your markdown file with m2d parser, and voilà! You have a layout ready.

import dash_mantine_components as dmc
from dash import Dash, html

from markdown2dash import parse

with open("../README.md") as f:
    md = f.read()


def render_toc(self, toc):
    paddings = {3: 0, 5: 40}
    links = [
        html.A(
            dmc.Text(text, color="dimmed", size="sm"),
            href="#" + hid,
            style={
                "textTransform": "capitalize",
                "textDecoration": "none",
                "paddingLeft": paddings[level],
            },
        )
        for level, text, hid in toc
    ]
    heading = dmc.Text("Table of Contents", mb=10, weight=500) if links else None
    return dmc.Stack([heading, *links], spacing=4, mt=20, mb=30)


layout = parse(md, toc_renderer=render_toc)

app = Dash(__name__)

app.layout = dmc.MantineProvider(
    dmc.Container(layout, size="lg", p=20),
    withGlobalStyles=True,
    withNormalizeCSS=True,
    theme={
        "primaryColor": "indigo",
        "colorScheme": "light",
        "fontFamily": "'Inter', sans-serif",
        "components": {
            "Table": {"defaultProps": {"striped": True, "withBorder": True}},
            "Alert": {"styles": {"title": {"fontWeight": 500}}},
        },
    },
)

if __name__ == "__main__":
    app.run(debug=True)

There's now styling by default, so you'll have to provide your own css. You can do that in two ways:

1. Wrap your layout in a MantineProvider and use it to style your page
2. Create CSS files. You can get started with the one provided in this repository: styles.css

Example App

You can also just run the example app included in this project locally.

python example/app.py

Available tokens and class names

m2d can render following types of tokens:

Special Directives

m2d includes some special directives enabling you to do a lot more than just rendering static markdown into a dash layout.

Executable Block

You can use the exec directive to embed the output of a python script as well as its source code. This directive expects that you have stored the output layout in the variable called component.

.. exec::example.component

Here's the output if you are viewing this in a dash app:

.. exec::example.component

You can hide the source code using the code argument, and the border using border.

.. exec::markdown2dash.example.component
    :code: false
    :border: false

Admonition

You can use admonition directive to add dmc.Alert components in your page. Admonition directive uses DashIconify to render icons as well.

.. admonition::Alert Title
    :icon: radix-icons:github-logo
    
    This is to show that now you can render alerts directly from the markdown.

Here's the output if you are viewing this in a dash app:

.. admonition::Alert Title :icon: radix-icons:github-logo

This is to show that now you can render alerts directly from the markdown.

Image

Render images using dmc.Image like this:

.. image::https://www.dash-mantine-components.com/assets/superman.jpeg
    :width: 300px
    :height: 300px

Here's the output if you are viewing this in a dash app:

.. image::https://www.dash-mantine-components.com/assets/superman.jpeg :width: 300px :height: 300px

Dash Component API Docs

It's very simple to add API docs of your component using m2d. You just have to specify the package and the component. Let's create one for DashIconify:

.. kwargs::DashIconify
    :library: dash_iconify

Here's the output if you are viewing this in a dash app:

.. kwargs::DashIconify :library: dash_iconify

Table of Contents

In order to get a table of contents using m2d, you need to pass a renderer functions that accepts a placeholder self and the actual inputs in the following way:

# a placeholder for self and a list of [<level>, <title>, <id>]
[
    (4, 'Installation', 'installation'),
    (4, 'Quickstart', 'quickstart'), 
    (5, 'Example App', 'example-app'),
    (4, 'Special Directives', 'special-directives'),
    (5, 'Dash Component API Docs', 'dash-component-api-docs'),
    (5, 'Table of Contents', 'table-of-contents')
]

Here's the renderer function used on this page:

def render_toc(self, toc):
    paddings = {4: 0, 5: 40}
    links = [
        html.A(
            dmc.Text(text, color="dimmed", size="sm"),
            href="#" + hid,
            style={
                "textTransform": "capitalize",
                "textDecoration": "none",
                "paddingLeft": paddings[level],
            },
        )
        for level, text, hid in toc
    ]
    heading = dmc.Text("Table of Contents", mb=10, weight=500) if links else None
    return dmc.Stack([heading, *links], spacing=4, mt=20, mb=30)

And then you can enable TOC lke this:

.. toc::
    :min_level: 3