Package: pelican-mau-reader
Mau Reader: A Plugin for PelicanMau Reader is a Pelican plugin that converts theMauformat into HTML.RequirementsThis plugin requires:Python 3.8+Pelican 4.5+Mau 2.0+InstallationThis plugin can be installed via the following command, which will also automatically install Mau itself:python -m pip install pelican-mau-readerAs long as you have not explicitly added aPLUGINSsetting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must addmau_readerto your existingPLUGINSlist. For more information, please see theHow to Use Pluginsdocumentation.UsageThe plugin automatically manages all Pelican content files ending with the extension:.mauMetadata shall be expressed as Mau variables under thepelicannamespace. 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 testThe 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 theconfigdictionary are available as variables, so you can specify global values that are valid for all documents.Custom templatesYou can override some or all Mau default HTML templates via thecustom_templatesconfiguration 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 footnotesThe 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 anchorsMau provides a simple function to compute IDs for headers, based on the content. The current function is:defheader_anchor(text,level):# Everything lowercasesanitised_text=text.lower()# Get only letters, numbers, dashes, and spacessanitised_text="".join(re.findall("[a-z0-9- ]+",sanitised_text))# Remove multiple spacessanitised_text="-".join(sanitised_text.split())returnsanitised_textThis provides deterministic header IDs that should suit the majority of cases. Should you need something different, you can provide your own function specifyingmau.header_anchor_functionin the configuration:MAU={"mau.header_anchor_function":lambdatext,level:"XYZ",}The example above returns the IDXYZfor all headers (not recommended as it is not unique). The argumentstextandlevelare respectively the text of the header itself and an integer representing the level of depth (e.g.,1forh1headers,2forh2headers, and so on).ContributingContributions 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 onexisting issues.To start contributing to this plugin, review theContributing to Pelicandocumentation, beginning with theContributing Codesection.LicenseThis project is licensed under the MIT license.