markdown2dash 0.1.1

Markdown-2-Dash

.. toc:: :min_level: 3

Markdown-2-Dash或M2D是从dash-mantine-components官方文档的源代码中派生出来的独立包。M2D的一些形式自文档开始以来就始终存在，但我认为更多的人可以利用这个来记录他们的dash应用或组件库。

查看这里，看看使用M2D解析后的README将是什么样子。渲染还完美地与暗黑模式兼容，无需任何额外代码。

.. admonition::注意 :icon: radix-icons:info-circled :color: red

The theme switcher has been added only for this demo, its not available as part of markdown2dash.

安装

pip install markdown2dash

poetry add markdown2dash

.. admonition::注意 :icon: radix-icons:info-circled :color: red

Latest dmc is based on REACT 18. You need to set REACT_VERSION=18.2.0 before starting the app. 

快速入门

M2D的README解析

让我们首先用M2D解析这个存储库的README。

.. admonition::注意 :icon: radix-icons:bookmark-filled :color: yellow

Make sure to include stylesheets for all extensions you are planning to use in your app.    

import dash_mantine_components as dmc
from dash import Dash

from markdown2dash import parse

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

layout = parse(md)

stylesheets = [
    "https://unpkg.com/@mantine/dates@7/styles.css",
    "https://unpkg.com/@mantine/code-highlight@7/styles.css",
    "https://unpkg.com/@mantine/charts@7/styles.css",
    "https://unpkg.com/@mantine/carousel@7/styles.css",
    "https://unpkg.com/@mantine/notifications@7/styles.css",
    "https://unpkg.com/@mantine/nprogress@7/styles.css",
]

app = Dash(__name__, external_stylesheets=stylesheets)


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

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

默认情况下没有样式，您需要提供自己的 CSS。您可以通过两种方式实现

1. 使用 MantineProvider 来样式化您的页面（如上所示）
2. 创建 CSS 文件。您可以从本存储库中提供的文件开始：styles.css

M2D 渲染的每个组件都将附加一个类名。

可用的令牌和类名

M2D 可以渲染以下类型的令牌

令牌	类名
链接	.m2d-link
段落	.m2d-paragraph
强调	.m2d-emphasis
粗体	.m2d-strong
代码跨度	.m2d-codespan
标题	.m2d-heading
主题分隔符	.m2d-thematic-break
块代码	.m2d-block-code
块引用	.m2d-block-quote
列表项	.m2d-list-item
列表	.m2d-list
删除线	.m2d-strikethrough
标记	.m2d-mark
表格	.m2d-table
表头	.m2d-table-head
表体	.m2d-table-body
行	.m2d-table-row
单元格	.m2d-table-cell
隐藏内容	.m2d-block-spoiler
注意	.m2d-block-admonition
分隔符	.m2d-block-divider
可执行块	.m2d-block-exec
图片	.m2d-block-image
dash 组件文档	.m2d-block-kwargs
源代码	.m2d-block-source
目录	.m2d-block-toc

特殊指令

M2D 包含一些特殊指令，这些指令可以让你做的不仅仅是将静态 Markdown 渲染成 dash 布局。

这些指令都是可扩展的，你可以直接覆盖渲染方法来满足自己的需求。默认渲染方法已包含在所有指令中。

可执行块

您可以使用 exec 指令来嵌入 Python 脚本的输出及其源代码。此指令期望您已将输出布局存储在名为 component 的变量中。

.. exec::example.navlink

以下是您在 dash 应用中查看时的输出

.. exec::example.navlink

您可以使用 code 参数隐藏源代码，并使用 border 隐藏边框。

.. exec::example.navlink
    :code: false
    :border: false

源代码

您可以使用 SourceCode 指令显示项目中的文件中的代码。文件路径相对于当前工作目录。

这是用于样式化此页面的 CSS。

.. source::example/assets/styles.css
    :language: css

.. source::example/assets/styles.css :language: css

注意

您可以使用 admonition 指令将 dmc.Alert 组件添加到您的页面中。Admonition 指令还使用 DashIconify 来渲染图标。

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

以下是您在 dash 应用中查看时的输出

.. admonition::Alert 标题 :icon: radix-icons:github-logo :variant: outline

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

图片

使用 dmc.Image 如此渲染图片

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

以下是您在 dash 应用中查看时的输出

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

dash 组件 API 文档

使用 M2D 添加组件的 API 文档非常简单。您只需指定包和组件。让我们为 DashIconify 创建一个

.. kwargs::DashIconify
    :library: dash_iconify

以下是您在 dash 应用中查看时的输出

.. kwargs::DashIconify :library: dash_iconify

目录

此指令将解析所有标题并创建一个如表所示的目录

# 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')
]

然后使用渲染方法渲染此目录。您可以通过以下方式启用目录

.. toc::
    :min_level: 3

分隔符

在 Markdown 文件中添加 --- 是添加分隔符的简单方法。

---

---

但是，假设您想给分隔符添加标签并自定义它。您可以使用分隔符指令来实现。

.. divider::Section Changed!
    :labelPosition: left

.. divider::Section Changed!

.. divider::Section Changed!
    :labelPosition: right

.. divider::章节已更改！ :labelPosition: left

.. divider::章节已更改！

.. divider::章节已更改！ :labelPosition: right

更多示例

任务列表

您可以创建如下任务列表，并将在 dash 应用中自动渲染复选框列表。

- [ ] Create README for library.
- [x] Resolve GitHub issues [here](https://github.com/snehilvj/dash-mantine-components).

• 为库创建 README。
• 解决 GitHub 问题 在此。

隐藏内容

创建如下这样的预告内容

>! In the final moments of Dune: Part Two...
>! Why does Paul need to marry Princess Irulan...
>! In the book, we learn that a dea...

这就是渲染后的样子（由dmc.Spoiler包裹）

！在《沙丘：第二部》的最后时刻，保罗·阿崔迪斯做了两件令人震惊的事情：他宣称他将与伊拉伦公主（弗洛伦斯·派格）结婚，然后，他派遣他的弗梅人部队进入宇宙，开始对大家族进行圣战。这是保罗自从《沙丘：第一部》以来一直看到的可怕的未来愿景。弗梅人和阿崔迪斯家族在阿瑞斯星上取得了胜利，但代价是大规模的战争，将烧毁半个宇宙。让我们分析一下这是如何发生的。！为什么保罗需要与伊拉伦公主结婚才能从沙德姆四世皇帝手中夺取王位？因为他控制了阿瑞斯上的香料，难道他不能杀掉所有人然后与他的真爱夏妮结婚吗？答案在书中。当保罗在书的最后一页看到伊拉伦时，他想，“这就是我的钥匙，”而在书的最后一页，他告诉夏妮，“我们必须遵守形式。”这意味着他想要在体系中获得权力。！在书中，我们了解到一项协议已经达成，“让贝内·吉赛尔特人登上王位，而伊拉伦就是他们培养的人。”在电影中，在一切最终崩溃之前，加乌斯·海伦·莫哈姆大主教告诉伊拉伦，“你们家族保持权力的唯一方法……你准备好了吗？”

嵌套列表

让我们尝试在嵌套列表中渲染各种项目。

1. Ingredients
   - spaghetti
   - marinara sauce
   - salt
2. Cooking
   1. Bring water to boil, add a pinch of salt and spaghetti.
   2. Cook until pasta is **tender**.
3. Serve: Drain the pasta on a plate. Add heated sauce.
4. No man is lonely eating spaghetti, it requires so much attention.

1. 配料
   • 意大利面
   • 马里纳拉酱
   • 盐
2. 烹饪
   1. 将水煮沸，加入少许盐和意大利面。
   2. 煮至意大利面变软。
3. 上菜：将意大利面沥干在盘子上。加入加热的酱汁。
4. 没有人吃饭时是孤独的，意大利面需要太多的注意力。

图表

您可以使用exec块在您的应用程序中添加图表。以下块将渲染一个在example/chart.py中定义的BarChart。

.. exec::example.chart
    :code: false
    :border: true

.. exec::example.chart :code: false :border: false

引用

生活就像npm install –你永远不知道你会得到什么。

添加自己的指令

您可以通过扩展BaseDirective类并创建一个新的解析器来创建一个新的指令。以下是如何添加一个新指令，在应用程序的右下角添加一个滚动到顶部按钮的示例。

.. source::example/scroll.py

相关的CSS类名为：m2d-block-scroll。

使用以下方式创建新的解析器

from markdown2dash import create_parser, DEFAULT_DIRECTIVES

parse = create_parser(DEFAULT_DIRECTIVES + [ScrollToTop()])
layout = parse(content)

以下是如何在Markdown中使用它的示例。

.. scroll::

.. scroll:

.. exec::example.theme :code: false :border: false