Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Datasette plugin for rendering Markdown

Project description

datasette-render-markdown

PyPI CircleCI License

Datasette plugin for rendering Markdown.

Installation

Install this plugin in the same environment as Datasette to enable this new functionality:

$ pip install datasette-render-markdown

Usage

You can explicitly list the columns you would like to treat as Markdown using plugin configuration in a metadata.json file.

Add a "datasette-render-markdown" configuration block and use a "columns" key to list the columns you would like to treat as Markdown values:

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

This will cause any body column in any table to be treated as markdown and safely rendered using Python-Markdown. The resulting HTML is then run through Bleach to avoid the risk of XSS security problems.

Save this to metadata.json and run Datasette with the --metadata flag to load this configuration:

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

The configuration block can be used at the top level, or it can be applied just to specific databases or tables. Here's how to apply it to just the entries table in the news.db database:

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

And here's how to apply it to every body column in every table in the news.db database:

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

Columns that match a naming convention

This plugin can also render markdown in any columns that match a specific naming convention.

By default, columns that have a name ending in _markdown will be rendered.

You can try this out using the following query:

select '# Hello there

* This is a list
* of items

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

You can configure a different list of wildcard patterns using the "patterns" configuration key. Here's how to render columns that end in either _markdown or _md:

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

To disable wildcard column matching entirely, set "patterns": [] in your plugin metadata configuration.

Markdown extensions

The Python-Markdown library that powers this plugin supports extensions, both bundled and third-party. These can be used to enable additional Markdown features such as table support.

You can configure support for extensions using the "extensions" key in your plugin metadata configuration.

Since extensions may introduce new HTML tags, you will also need to add those tags to the list of tags that are allowed by the Bleach sanitizer. You can do that using the "extra_tags" key, and you can whitelist additional HTML attributes using "extra_attrs". See the Bleach documentation for more information on this.

Here's how to enable support for Markdown tables:

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

GitHub-Flavored Markdown

Enabling GitHub-Flavored Markdown (useful for if you are working with data imported from GitHub using github-to-sqlite) is a little more complicated.

First, you will need to install the py-gfm package:

$ pip install py-gfm

Note that py-gfm has a bug that causes it to pin to Markdown<3.0 - so if you are using it you should install it before installing datasette-render-markdown to ensure you get a compatibly version of that dependency.

Now you can configure it like this. Note that the extension name is mdx_gfm:GithubFlavoredMarkdownExtension and you need to whitelist several extra HTML tags and attributes:

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

The <input type="" checked disabled> attributes are needed to support rendering checkboxes in issue descriptions.

Markdown in templates

The plugin also adds a new template function: render_markdown(value). You can use this in your templates like so:

{{ render_markdown("""
# This is markdown

* One
* Two
* Three
""") }}

You can load additional extensions and whitelist tags by passing extra arguments to the function like this:

{{ 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"])) }}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for datasette-render-markdown, version 1.1.2
Filename, size File type Python version Upload date Hashes
Filename, size datasette_render_markdown-1.1.2-py3-none-any.whl (8.7 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page