datasette-render-markdown

用于渲染 Markdown 的 Datasette 插件。

安装

在 Datasette 所在的同一环境中安装此插件即可启用此新功能

datasette install datasette-render-markdown

使用方法

您可以使用 metadata.json 文件中的插件配置来明确列出您希望作为 Markdown 处理的列。

添加一个 "datasette-render-markdown" 配置块，并使用 "columns" 键列出您希望作为 Markdown 值处理的列

{
    "plugins": {
        "datasette-render-markdown": {
            "columns": ["body"]
        }
    }
}

这将导致任何表中的 body 列都被视为 markdown 并使用 Python-Markdown 安全地渲染。然后，生成的 HTML 将通过 Bleach 处理，以避免 XSS 安全风险。

将其保存到 metadata.json 并使用 --metadata 标志运行 Datasette 以加载此配置

$ datasette serve mydata.db --metadata metadata.json

此配置块可以在顶级使用，也可以仅应用于特定的数据库或表。以下是将其仅应用于 news.db 数据库中的 entries 表的方法

{
    "databases": {
        "news": {
            "tables": {
                "entries": {
                    "plugins": {
                        "datasette-render-markdown": {
                            "columns": ["body"]
                        }
                    }
                }
            }
        }
    }
}

以下是将其应用于 news.db 数据库中所有表的每个 body 列的方法

{
    "databases": {
        "news": {
            "plugins": {
                "datasette-render-markdown": {
                    "columns": ["body"]
                }
            }
        }
    }
}

符合命名约定的列

此插件还可以渲染任何符合特定命名约定的列中的 markdown。

默认情况下，名称以 _markdown 结尾的列将被渲染。

您可以使用以下查询尝试此功能

select '# Hello there

* This is a list
* of items

[And a link](https://github.com/simonw/datasette-render-markdown).'
as demo_markdown

您可以使用 "patterns" 配置键配置不同的通配符模式列表。以下是渲染以 _markdown 或 _md 结尾的列的方法

{
    "plugins": {
        "datasette-render-markdown": {
            "patterns": ["*_markdown", "*_md"]
        }
    }
}

要完全禁用通配符列匹配，请在您的插件元数据配置中设置 "patterns": []。

Markdown 扩展

此插件所依赖的 Python-Markdown 库支持扩展，包括捆绑的和第三方的。这些扩展可用于启用额外的 Markdown 功能，例如表格支持。

您可以使用插件元数据配置中的 "extensions" 键来配置对扩展的支持。

由于扩展可能会引入新的 HTML 标签，您还需要将这些标签添加到 Bleach 清理器允许的标签列表中。您可以使用 "extra_tags" 键执行此操作，并使用 "extra_attrs" 允许额外的 HTML 属性。有关更多信息，请参阅Bleach 文档。

以下是启用对Markdown 表格的支持的方法

{
    "plugins": {
        "datasette-render-markdown": {
            "extensions": ["tables"],
            "extra_tags": ["table", "thead", "tr", "th", "td", "tbody"]
        }
    }
}

GitHub-Flavored Markdown

启用 GitHub-Flavored Markdown（如果您正在使用从 GitHub 导入的数据，例如使用 github-to-sqlite 导入的数据，这将很有用）会稍微复杂一些。

首先，您需要安装 py-gfm 包

$ pip install py-gfm

请注意，py-gfm 有一个 bug 会导致其固定到 Markdown<3.0 - 因此如果您使用它，应在安装 datasette-render-markdown *之前*安装它，以确保您获得该依赖项的兼容版本。

现在您可以像这样配置它。请注意，扩展名称是 mdx_gfm:GithubFlavoredMarkdownExtension，您需要允许列出一些额外的 HTML 标签和属性

{
    "plugins": {
        "datasette-render-markdown": {
            "extra_tags": [
                "hr",
                "br",
                "details",
                "summary",
                "input"
            ],
            "extra_attrs": {
                "input": [
                    "type",
                    "disabled",
                    "checked"
                ],
            },
            "extensions": [
                "mdx_gfm:GithubFlavoredMarkdownExtension"
            ]
        }
    }
}

需要 <input type="" checked="" disabled=""> 属性来支持在 issue 描述中渲染复选框。

模板中的 Markdown

此插件引入了一个新的模板标签：{% markdown %}...{% endmarkdown %} - 可用于在您的 Jinja 模板中渲染 Markdown。

{% markdown %}
# This will be rendered as markdown
{% endmarkdown %}

您可以在 {% markdown %} 标签上使用属性来启用扩展并允许列出额外的标签和属性

示例

段落

{% endmarkdown %}">

{% markdown
  extensions="tables"
  extra_tags="table thead tr th td tbody" 
  extra_attrs="p:id,class a:name,href" %}
## Markdown table

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

<a href="https://www.example.com/" name="namehere">Examplea>
<p id="paragraph" class="klass">Paragraphp>
{% endmarkdown %}

extensions= 和 extra_tags= 属性接受一个空格分隔的值列表。

extra_attrs= 属性接受一个空格分隔的 tag:attr1,attr2 值列表 - 每个标签可以指定一个或多个应被允许的属性。

您也可以使用 {{ render_markdown(...) }} 函数，如下所示

{{ render_markdown("""
## Markdown table

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
""", extensions=["tables"],
    extra_tags=["table", "thead", "tr", "th", "td", "tbody"])) }}

推荐使用 {% markdown %} 标签，因为它避免了在您的 Markdown 内容中对引号进行 \" 转义的需要。

datasette-render-markdown by simonw