| Name | pelican-mau-reader JSON |
| Version |
3.0.1
JSON |
| download |
| home_page | |
| Summary | Pelican plugin that converts Mau-formatted content into HTML |
| upload_time | 2023-09-11 06:40:43 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | <4.0,>=3.8.1 |
| license | MIT |
| keywords |
pelican
plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mau Reader: A Plugin for Pelican
[](https://github.com/pelican-plugins/mau-reader/actions)
[](https://pypi.org/project/pelican-mau-reader/)
[](https://pypi.org/project/pelican-mau-reader/)
Mau Reader is a Pelican plugin that converts the [Mau](https://github.com/Project-Mau/mau) format into HTML.
## Requirements
This plugin requires:
* Python 3.8+
* Pelican 4.5+
* Mau 2.0+
## Installation
This plugin can be installed via the following command, which will also automatically install Mau itself:
python -m pip install pelican-mau-reader
As long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `mau_reader` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.
## 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:
``` python
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:
``` python
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:
``` python
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:
``` python
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.
[existing issues]: https://github.com/pelican-plugins/mau-reader/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
## License
This project is licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": "",
"name": "pelican-mau-reader",
"maintainer": "",
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": "",
"keywords": "pelican,plugin",
"author": "",
"author_email": "Leonardo Giordani <giordani.leonardo@gmail.com>, Justin Mayer <entroP@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/5a/035eab2313d8ae1272b5b074d180960f974c6bd553a42c127a6c23367cf8/pelican_mau_reader-3.0.1.tar.gz",
"platform": null,
"description": "# Mau Reader: A Plugin for Pelican\n\n[](https://github.com/pelican-plugins/mau-reader/actions)\n[](https://pypi.org/project/pelican-mau-reader/)\n[](https://pypi.org/project/pelican-mau-reader/)\n\n\nMau Reader is a Pelican plugin that converts the [Mau](https://github.com/Project-Mau/mau) format into HTML.\n\n## Requirements\n\nThis plugin requires:\n\n* Python 3.8+\n* Pelican 4.5+\n* Mau 2.0+\n\n## Installation\n\nThis plugin can be installed via the following command, which will also automatically install Mau itself:\n\n python -m pip install pelican-mau-reader\n\nAs long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `mau_reader` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.\n\n## Usage\n\nThe plugin automatically manages all Pelican content files ending with the extension: `.mau`\n\nMetadata shall be expressed as Mau variables under the `pelican` namespace. For example:\n\n```\n:pelican.title:Test Mau file with content\n:pelican.date:2021-02-17 13:00:00\n:pelican.modified:2021-02-17 14:00:00\n:pelican.category:test\n:pelican.tags:foo, bar, foobar\n:pelican.summary:I have a lot to test\n```\n\nThe 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.\n\nAll values in the `config` dictionary are available as variables, so you can specify global values that are valid for all documents.\n\n## Custom templates\n\nYou 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:\n\n``` python\nMAU = {\n \"custom_templates\": {\n \"header.html\": (\n '<h{{ level }} id=\"{{ anchor }}\">'\n \"{{ value }}\"\n '<a href=\"#{{ anchor }}\" title=\"Permanent link\">\u00b6</a>'\n \"</h{{ level }}>\"\n )\n }\n}\n```\n\n\u2026 and if you want to limit that to only headers of level 1 and 2 you can use:\n\n``` python\nMAU = {\n \"custom_templates\": {\n \"header.html\": (\n '<h{{ level }} id=\"{{ anchor }}\">'\n \"{{ value }}\"\n '{% if level <= 2 %}<a href=\"#{{ anchor }}\" title=\"Permanent link\">\u00b6</a>{% endif %}'\n \"</h{{ level }}>\"\n )\n }\n}\n```\n\n## Table of contents and footnotes\n\nThe 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:`.\n\n## Custom header anchors\n\nMau provides a simple function to compute IDs for headers, based on the content. The current function is:\n\n``` python\ndef header_anchor(text, level):\n # Everything lowercase\n sanitised_text = text.lower()\n\n # Get only letters, numbers, dashes, and spaces\n sanitised_text = \"\".join(re.findall(\"[a-z0-9- ]+\", sanitised_text))\n\n # Remove multiple spaces\n sanitised_text = \"-\".join(sanitised_text.split())\n\n return sanitised_text\n```\n\nThis 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:\n\n``` python\nMAU = {\n \"mau.header_anchor_function\": lambda text, level: \"XYZ\",\n}\n```\n\nThe 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).\n\n## Contributing\n\nContributions 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][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[existing issues]: https://github.com/pelican-plugins/mau-reader/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\n## License\n\nThis project is licensed under the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pelican plugin that converts Mau-formatted content into HTML",
"version": "3.0.1",
"project_urls": {
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/mau-reader",
"Issue Tracker": "https://github.com/pelican-plugins/mau-reader/issues"
},
"split_keywords": [
"pelican",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53e7ac103e17a8b043ab4208631ba4d787497875c06db1921f3867be5651f0b5",
"md5": "7bd498e1187ab3c4fac84b6f49785246",
"sha256": "8e8301b81bdd7c9b4fe3061def121ce7c558332e4964417d070b1a3942f8b5f4"
},
"downloads": -1,
"filename": "pelican_mau_reader-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bd498e1187ab3c4fac84b6f49785246",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 6151,
"upload_time": "2023-09-11T06:40:42",
"upload_time_iso_8601": "2023-09-11T06:40:42.093005Z",
"url": "https://files.pythonhosted.org/packages/53/e7/ac103e17a8b043ab4208631ba4d787497875c06db1921f3867be5651f0b5/pelican_mau_reader-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb5a035eab2313d8ae1272b5b074d180960f974c6bd553a42c127a6c23367cf8",
"md5": "11ccb0540b1a8b2799166f426c201474",
"sha256": "b853d0b10e0846f59261b51337d4ed2a3d7ae5a67e7f9826e32685a00eb9310d"
},
"downloads": -1,
"filename": "pelican_mau_reader-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "11ccb0540b1a8b2799166f426c201474",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 8638,
"upload_time": "2023-09-11T06:40:43",
"upload_time_iso_8601": "2023-09-11T06:40:43.728681Z",
"url": "https://files.pythonhosted.org/packages/bb/5a/035eab2313d8ae1272b5b074d180960f974c6bd553a42c127a6c23367cf8/pelican_mau_reader-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-11 06:40:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "mau-reader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-mau-reader"
}
