Skip to main content

Pelican plugin that converts Mau-formatted content into HTML

Project description

Mau Reader: A Plugin for Pelican

Build Status PyPI Version License

Mau Reader is a Pelican plugin that converts the Mau format into HTML.

Requirements

This plugin requires:

  • Python 3.6+
  • Pelican 4.5+
  • Mau 1.3+

Installation

This plugin can be installed via the following command, which will also automatically install Mau itself:

python -m pip install pelican-mau-reader

Usage

The plugin automatically manages all Pelican content files ending with the extension: .mau

Metadata shall be expressed as Mau variables under the pelican namespace. For example:

:pelican.title:Test Mau file with content
:pelican.date:2021-02-17 13:00:00
:pelican.modified:2021-02-17 14:00:00
:pelican.category:test
:pelican.tags:foo, bar, foobar
:pelican.summary:I have a lot to test

The value of a metadata field is a string, just as it is in the standard Markdown format. Please note that Mau variable values include all characters after the colon, spaces included.

All values in the config dictionary are available as variables, so you can specify global values that are valid for all documents.

Custom templates

You can override some or all Mau default HTML templates via the custom_templates configuration variable. For example, should you want to add a permanent link to all headers you can define:

MAU = {
    "custom_templates": {
        "header.html": (
            '<h{{ level }} id="{{ anchor }}">'
            "{{ value }}"
            '<a href="#{{ anchor }}" title="Permanent link">¶</a>'
            "</h{{ level }}>"
        )
    }
}

… and if you want to limit that to only headers of level 1 and 2 you can use:

MAU = {
    "custom_templates": {
        "header.html": (
            '<h{{ level }} id="{{ anchor }}">'
            "{{ value }}"
            '{% if level <= 2 %}<a href="#{{ anchor }}" title="Permanent link">¶</a>{% endif %}'
            "</h{{ level }}>"
        )
    }
}

Table of contents and footnotes

The TOC (Table of Contents) and footnotes are specific to each content file and can be inserted as usual with the Mau commands ::toc: and ::footnotes:.

Custom header anchors

Mau provides a simple function to compute IDs for headers, based on the content. The current function is:

def header_anchor(text, level):
    # Everything lowercase
    sanitised_text = text.lower()

    # Get only letters, numbers, dashes, and spaces
    sanitised_text = "".join(re.findall("[a-z0-9- ]+", sanitised_text))

    # Remove multiple spaces
    sanitised_text = "-".join(sanitised_text.split())

    return sanitised_text

This provides deterministic header IDs that should suit the majority of cases. Should you need something different, you can provide your own function specifying mau.header_anchor_function in the configuration:

MAU = {
    "mau.header_anchor_function": lambda text, level: "XYZ",
}

The example above returns the ID XYZ for all headers (not recommended as it is not unique). The arguments text and level are respectively the text of the header itself and an integer representing the level of depth (e.g., 1 for h1 headers, 2 for h2 headers, and so on).

Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.

To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.

License

This project is licensed under the MIT license.

Project details


Download files

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

Source Distribution

pelican-mau-reader-1.0.0.tar.gz (6.2 kB view details)

Uploaded Source

Built Distribution

pelican_mau_reader-1.0.0-py3-none-any.whl (7.1 kB view details)

Uploaded Python 3

File details

Details for the file pelican-mau-reader-1.0.0.tar.gz.

File metadata

  • Download URL: pelican-mau-reader-1.0.0.tar.gz
  • Upload date:
  • Size: 6.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.5 CPython/3.9.2 Linux/5.4.0-1040-azure

File hashes

Hashes for pelican-mau-reader-1.0.0.tar.gz
Algorithm Hash digest
SHA256 682c78ed4df656fbd186ff982dc75120497900920a9b5d8488d8364bcf8e9dc4
MD5 2c5d54d840bb12070d1c7d18a7d7d0ed
BLAKE2b-256 2865adcfd95204cc8fb1c5d48840022004791dc9f20524dd77b97b6c5e0977e7

See more details on using hashes here.

Provenance

File details

Details for the file pelican_mau_reader-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for pelican_mau_reader-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a72a3800ca628f8ba0ad8a19bf4f7d7150286ccb9699df1b51449e84c28b64c7
MD5 595bd0f00da684872aea98bc06821bc6
BLAKE2b-256 623114ce0ee994c94117805a147b88f1e47f3f1900deace6dfb2042c21ab2dde

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page