# MyST Reader: A Plugin for Pelican
[](https://github.com/ashwinvis/myst-reader/actions)
[](https://results.pre-commit.ci/latest/github/ashwinvis/myst-reader/main)
[](https://pypi.org/project/pelican-myst-reader/)
*MyST Reader* is a [Pelican][] plugin that converts documents written in [MyST’s variant of Markdown][] into HTML.
## Requirements
This plugin requires:
- Python 3.9 or higher
## Installation
This plugin can be installed via:
```bash
python -m pip install pelican-myst-reader
```
As soon as the plugin is installed, it will automatically be used by Pelican to parse and render all Markdown files with the MyST syntax.
## Writing MyST content
MyST syntax is a superset of [CommonMark][]. So if you feed your Pelican site with
non-MyST Markdown files or other variants, most of them will probably renders as they were with this plugin.
You can then augment your plain Markdown with [MyST syntax](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) to get access to more features. You can play with the [MyST live preview](https://myst-parser.readthedocs.io/en/latest/live-preview.html) to see what is possible.
### File Metadata
The plugin expects all Markdown files to start with a YAML-formatted content header, as shown below.
```yaml
---
title: "<post-title>"
author: "<author-name>"
date: "<date>"
summary: |
The summary (can be on more than one line)...
---
```
If the values of the metadata can include MyST syntax, in which case, the field
name should be added to the [`FORMATTED_FIELDS`](https://docs.getpelican.com/en/latest/settings.html#basic-settings) list variable in
`pelicanconf.py`.
> ⚠️ **Note:** The YAML-formatted header shown above is syntax specific to MyST
> for specifying content metadata. This maybe different from Pelican’s
> front-matter format. If you ever decide to stop using this plugin and switch
> to Pelican’s default Markdown handling, you may need to switch your
> front-matter metadata to [Python-Markdown’s Meta-Data
> format](https://python-markdown.github.io/extensions/meta_data/).
As a compromise and in order to support both metadata formats (although this
means deviating away from MyST standard), title case headers are acceptable.
The advantage is that files are compatible with both MyST reader and Pelican's
Markdown reader.
```yaml
---
Title: "<post-title>"
Author: "<author-name>"
Date: "<date>"
---
```
For more information on Pelican's default metadata format please visit the link below:
- [Pelican’s default metadata format](https://docs.getpelican.com/en/stable/content.html#file-metadata)
## Configuration
The plugin supports passing options to influence how MyST is parsed and renderered. This is done by
configuring your Pelican settings file (e.g., `pelicanconf.py`):
### Docutils Renderer
By default MyST rely on [Docutils](https://docutils.sourceforge.io/) to parse and render its syntax. That's [because MyST primarily targets Sphinx](https://myst-parser.readthedocs.io/en/latest/develop/background.html#the-relationship-between-myst-restructuredtext-and-sphinx).
To produce HTML for Pelican, *MyST Reader* uses Docutils too (and more precisely its [HTML5 Writer](https://docutils.sourceforge.io/docs/user/config.html#html5-writer)).
This plugin setup Docutils with good settings by defaults. But you can still influence it
with the `MYST_DOCUTILS_SETTINGS` setting.
Here is an example of configuration in `pelicanconf.py`:
```python
MYST_DOCUTILS_SETTINGS = {
### Docutils settings ###
"strip_comments": True,
### MyST settings ###
"myst_gfm_only": True,
"myst_substitutions": {
"key1": "I'm a **substitution**",
},
"myst_enable_extensions": {
"amsmath",
"dollarmath",
},
}
```
See how the `MYST_DOCUTILS_SETTINGS` setting is used to pass both:
- [Docutils configuration](https://docutils.sourceforge.io/docs/user/config.html)
- [MyST parser configuration](https://myst-parser.readthedocs.io/en/latest/configuration.html#docutils-configuration), including
Also notice how:
- MyST-specific settings are prefixed with `myst_`
- the list of additional [MyST extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) to activate is set with `myst_enable_extensions`
> ⚠️ **Note:** `MYST_DOCUTILS_SETTINGS` accepts the same parameters as [Pelican’s `DOCUTILS_SETTINGS`](https://docs.getpelican.com/en/latest/settings.html#basic-settings). We could have reused them but we [decided to keep them separate](https://github.com/ashwinvis/myst-reader/pull/14#discussion_r1240757130) for clarity.
### Sphinx Renderer
*MyST Reader* also supports an alternative rendering mode using [Sphinx](https://www.sphinx-doc.org).
You can force this rendering mode for all files with:
```python
MYST_FORCE_SPHINX = True
```
> ⚠️ **Note:** Sphinx rendering is way slower (~2.5x on my machine), as it setups behind the scene a standalone Sphinx project and sequentially run a full build for each page.
If set to `False`, which is the default, an heuristic is used to determine for each file if Sphinx should be used instead of the default Docutils renderer from the section above.
This heuristic activates the Sphinx renderer if any of the following rule is met:
- a math extension from MyST
is enabled ([`dollarmath` or `amsmath`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#math-shortcuts)) in `MYST_SPHINX_SETTINGS`
- BibTeX files are found
Now this rendering mode also has its own dedicated configuration setting: `MYST_SPHINX_SETTINGS`. It is a dictionary that will be used to build a `conf.py` file to be passed to the Sphinx builder.
Here is an example of configuration in `pelicanconf.py`:
```python
MYST_SPHINX_SETTINGS = {
### Sphinx settings ###
"nitpicky": True,
"keep_warnings": True,
### MyST settings ###
"myst_gfm_only": True,
"myst_substitutions": {
"key1": "I'm a **substitution**",
},
"myst_enable_extensions": {
"amsmath",
"dollarmath",
},
}
```
Like the previous renderer, it supports both settings:
- [Sphinx configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html)
- [MyST parser configuration](https://myst-parser.readthedocs.io/en/latest/configuration.html#global-configuration)
And again:
- MyST-specific settings are prefixed with `myst_`
- the list of additional [MyST extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) to activate is set with `myst_enable_extensions`
### Deprecated `MYST_EXTENSIONS`
There is a dedicated `MYST_EXTENSIONS` setting to activate MyST extensions. But it is deprecated in favor of the `MYST_DOCUTILS_SETTINGS["myst_enable_extensions"]` and `MYST_SPHINX_SETTINGS["myst_enable_extensions"]` settings.
It is still loaded up by *MyST Reader* for backward compatibility but will be ignored in a future release.
If `MYST_EXTENSIONS` is set, it will be used to populate `MYST_DOCUTILS_SETTINGS["myst_enable_extensions"]` and `MYST_SPHINX_SETTINGS["myst_enable_extensions"]`.
### Reading Time
This plugin may be used to calculate the estimated reading time of articles and pages by setting `CALCULATE_READING_TIME` to `True` in your Pelican settings file:
```python
CALCULATE_READING_TIME = True
```
You may display the estimated reading time using the `{{ article.reading_time }}` or `{{ page.reading_time }}` template variables. The unit of time will be displayed as “minute” for reading times less than or equal to one minute, or “minutes” for those greater than one minute.
The reading time is calculated by dividing the number of words by the reading speed, which is the average number words read in a minute.
The default value for reading speed is set to 200 words per minute, but may be customized by setting `READING_SPEED` to the desired words per minute value in your Pelican settings file:
```python
READING_SPEED = <words-per-minute>
```
The number of words in a document is calculated using the [Markdown Word Count](https://github.com/gandreadis/markdown-word-count) package.
## Limitations
This plugin converts [MyST’s variant of Markdown][] into HTML for Pelican. MyST being a
superset of [CommonMark][CommonMark] should cover most Markdown variants. But
strictly speaking, conversion from other Markdown variants is unsupported.
Converting to output formats other than HTML is also unsupported.
## 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.
Special thanks to
- [Kevin Deldycke](https://kevin.deldycke.com/)
- [Pierre Augier](http://legi.grenoble-inp.fr/people/Pierre.Augier/)
for their improvements and feedback on this plugin. Kudos to the [pelican-pandoc-reader](https://pypi.org/project/pelican-pandoc-reader/) plugin which provided the foundation to build this plugin on.
[existing issues]: https://github.com/ashwinvis/myst-reader/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
## License
This project is licensed under the AGPL-3.0 license.
[Pelican]: https://getpelican.com
[MyST’s variant of Markdown]: https://myst-parser.readthedocs.io/en/latest/using/syntax.html
[CommonMark]: https://commonmark.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/ashwinvis/myst-reader",
"name": "pelican-myst-reader",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "pelican, plugin, markdown, myst",
"author": "Ashwin Vishnu",
"author_email": "dev@fluid.quest",
"download_url": "https://files.pythonhosted.org/packages/71/01/503463a7a4c396944b632005177b5dbdbbca0c109f22a229b062e479aebd/pelican_myst_reader-1.3.0.tar.gz",
"platform": null,
"description": "# MyST Reader: A Plugin for Pelican\n\n[](https://github.com/ashwinvis/myst-reader/actions)\n[](https://results.pre-commit.ci/latest/github/ashwinvis/myst-reader/main)\n[](https://pypi.org/project/pelican-myst-reader/)\n\n\n*MyST Reader* is a [Pelican][] plugin that converts documents written in [MyST\u2019s variant of Markdown][] into HTML.\n\n## Requirements\n\nThis plugin requires:\n\n- Python 3.9 or higher\n\n## Installation\n\nThis plugin can be installed via:\n\n```bash\npython -m pip install pelican-myst-reader\n```\n\nAs soon as the plugin is installed, it will automatically be used by Pelican to parse and render all Markdown files with the MyST syntax.\n\n## Writing MyST content\n\nMyST syntax is a superset of [CommonMark][]. So if you feed your Pelican site with\nnon-MyST Markdown files or other variants, most of them will probably renders as they were with this plugin.\n\nYou can then augment your plain Markdown with [MyST syntax](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) to get access to more features. You can play with the [MyST live preview](https://myst-parser.readthedocs.io/en/latest/live-preview.html) to see what is possible.\n\n### File Metadata\n\nThe plugin expects all Markdown files to start with a YAML-formatted content header, as shown below.\n\n```yaml\n---\ntitle: \"<post-title>\"\nauthor: \"<author-name>\"\ndate: \"<date>\"\nsummary: |\n The summary (can be on more than one line)...\n---\n```\n\nIf the values of the metadata can include MyST syntax, in which case, the field\nname should be added to the [`FORMATTED_FIELDS`](https://docs.getpelican.com/en/latest/settings.html#basic-settings) list variable in\n`pelicanconf.py`.\n\n> \u26a0\ufe0f **Note:** The YAML-formatted header shown above is syntax specific to MyST\n> for specifying content metadata. This maybe different from Pelican\u2019s\n> front-matter format. If you ever decide to stop using this plugin and switch\n> to Pelican\u2019s default Markdown handling, you may need to switch your\n> front-matter metadata to [Python-Markdown\u2019s Meta-Data\n> format](https://python-markdown.github.io/extensions/meta_data/).\n\nAs a compromise and in order to support both metadata formats (although this\nmeans deviating away from MyST standard), title case headers are acceptable.\nThe advantage is that files are compatible with both MyST reader and Pelican's\nMarkdown reader.\n\n```yaml\n---\nTitle: \"<post-title>\"\nAuthor: \"<author-name>\"\nDate: \"<date>\"\n---\n```\n\nFor more information on Pelican's default metadata format please visit the link below:\n\n- [Pelican\u2019s default metadata format](https://docs.getpelican.com/en/stable/content.html#file-metadata)\n\n## Configuration\n\nThe plugin supports passing options to influence how MyST is parsed and renderered. This is done by\nconfiguring your Pelican settings file (e.g., `pelicanconf.py`):\n\n### Docutils Renderer\n\nBy default MyST rely on [Docutils](https://docutils.sourceforge.io/) to parse and render its syntax. That's [because MyST primarily targets Sphinx](https://myst-parser.readthedocs.io/en/latest/develop/background.html#the-relationship-between-myst-restructuredtext-and-sphinx).\n\nTo produce HTML for Pelican, *MyST Reader* uses Docutils too (and more precisely its [HTML5 Writer](https://docutils.sourceforge.io/docs/user/config.html#html5-writer)).\n\nThis plugin setup Docutils with good settings by defaults. But you can still influence it\nwith the `MYST_DOCUTILS_SETTINGS` setting.\n\nHere is an example of configuration in `pelicanconf.py`:\n\n```python\nMYST_DOCUTILS_SETTINGS = {\n ### Docutils settings ###\n \"strip_comments\": True,\n\n ### MyST settings ###\n \"myst_gfm_only\": True,\n \"myst_substitutions\": {\n \"key1\": \"I'm a **substitution**\",\n },\n \"myst_enable_extensions\": {\n \"amsmath\",\n \"dollarmath\",\n },\n}\n```\n\nSee how the `MYST_DOCUTILS_SETTINGS` setting is used to pass both:\n- [Docutils configuration](https://docutils.sourceforge.io/docs/user/config.html)\n- [MyST parser configuration](https://myst-parser.readthedocs.io/en/latest/configuration.html#docutils-configuration), including\n\nAlso notice how:\n- MyST-specific settings are prefixed with `myst_`\n- the list of additional [MyST extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) to activate is set with `myst_enable_extensions`\n\n> \u26a0\ufe0f **Note:** `MYST_DOCUTILS_SETTINGS` accepts the same parameters as [Pelican\u2019s `DOCUTILS_SETTINGS`](https://docs.getpelican.com/en/latest/settings.html#basic-settings). We could have reused them but we [decided to keep them separate](https://github.com/ashwinvis/myst-reader/pull/14#discussion_r1240757130) for clarity.\n\n### Sphinx Renderer\n\n*MyST Reader* also supports an alternative rendering mode using [Sphinx](https://www.sphinx-doc.org).\n\nYou can force this rendering mode for all files with:\n\n```python\nMYST_FORCE_SPHINX = True\n```\n\n> \u26a0\ufe0f **Note:** Sphinx rendering is way slower (~2.5x on my machine), as it setups behind the scene a standalone Sphinx project and sequentially run a full build for each page.\n\nIf set to `False`, which is the default, an heuristic is used to determine for each file if Sphinx should be used instead of the default Docutils renderer from the section above.\n\nThis heuristic activates the Sphinx renderer if any of the following rule is met:\n- a math extension from MyST\nis enabled ([`dollarmath` or `amsmath`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#math-shortcuts)) in `MYST_SPHINX_SETTINGS`\n- BibTeX files are found\n\nNow this rendering mode also has its own dedicated configuration setting: `MYST_SPHINX_SETTINGS`. It is a dictionary that will be used to build a `conf.py` file to be passed to the Sphinx builder.\n\nHere is an example of configuration in `pelicanconf.py`:\n```python\nMYST_SPHINX_SETTINGS = {\n ### Sphinx settings ###\n \"nitpicky\": True,\n \"keep_warnings\": True,\n\n ### MyST settings ###\n \"myst_gfm_only\": True,\n \"myst_substitutions\": {\n \"key1\": \"I'm a **substitution**\",\n },\n \"myst_enable_extensions\": {\n \"amsmath\",\n \"dollarmath\",\n },\n}\n```\n\nLike the previous renderer, it supports both settings:\n- [Sphinx configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html)\n- [MyST parser configuration](https://myst-parser.readthedocs.io/en/latest/configuration.html#global-configuration)\n\nAnd again:\n- MyST-specific settings are prefixed with `myst_`\n- the list of additional [MyST extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) to activate is set with `myst_enable_extensions`\n\n### Deprecated `MYST_EXTENSIONS`\n\nThere is a dedicated `MYST_EXTENSIONS` setting to activate MyST extensions. But it is deprecated in favor of the `MYST_DOCUTILS_SETTINGS[\"myst_enable_extensions\"]` and `MYST_SPHINX_SETTINGS[\"myst_enable_extensions\"]` settings.\n\nIt is still loaded up by *MyST Reader* for backward compatibility but will be ignored in a future release.\n\nIf `MYST_EXTENSIONS` is set, it will be used to populate `MYST_DOCUTILS_SETTINGS[\"myst_enable_extensions\"]` and `MYST_SPHINX_SETTINGS[\"myst_enable_extensions\"]`.\n\n### Reading Time\n\nThis plugin may be used to calculate the estimated reading time of articles and pages by setting `CALCULATE_READING_TIME` to `True` in your Pelican settings file:\n\n```python\nCALCULATE_READING_TIME = True\n```\n\nYou may display the estimated reading time using the `{{ article.reading_time }}` or `{{ page.reading_time }}` template variables. The unit of time will be displayed as \u201cminute\u201d for reading times less than or equal to one minute, or \u201cminutes\u201d for those greater than one minute.\n\nThe reading time is calculated by dividing the number of words by the reading speed, which is the average number words read in a minute.\n\nThe default value for reading speed is set to 200 words per minute, but may be customized by setting `READING_SPEED` to the desired words per minute value in your Pelican settings file:\n\n```python\nREADING_SPEED = <words-per-minute>\n```\n\nThe number of words in a document is calculated using the [Markdown Word Count](https://github.com/gandreadis/markdown-word-count) package.\n\n## Limitations\n\nThis plugin converts [MyST\u2019s variant of Markdown][] into HTML for Pelican. MyST being a\nsuperset of [CommonMark][CommonMark] should cover most Markdown variants. But\nstrictly speaking, conversion from other Markdown variants is unsupported.\n\nConverting to output formats other than HTML is also unsupported.\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\nSpecial thanks to\n- [Kevin Deldycke](https://kevin.deldycke.com/)\n- [Pierre Augier](http://legi.grenoble-inp.fr/people/Pierre.Augier/)\n\nfor their improvements and feedback on this plugin. Kudos to the [pelican-pandoc-reader](https://pypi.org/project/pelican-pandoc-reader/) plugin which provided the foundation to build this plugin on.\n\n[existing issues]: https://github.com/ashwinvis/myst-reader/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\n## License\n\nThis project is licensed under the AGPL-3.0 license.\n\n[Pelican]: https://getpelican.com\n[MyST\u2019s variant of Markdown]: https://myst-parser.readthedocs.io/en/latest/using/syntax.html\n[CommonMark]: https://commonmark.org/\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Pelican plugin for converting MyST's Markdown variant to HTML.",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://docs.getpelican.com",
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/ashwinvis/myst-reader",
"Issue Tracker": "https://github.com/ashwinvis/myst-reader/issues",
"Repository": "https://github.com/ashwinvis/myst-reader"
},
"split_keywords": [
"pelican",
" plugin",
" markdown",
" myst"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9832b4e391aabc9e01432d9d01601b1fbdd82ee0bf51d823678f04f30ab784d3",
"md5": "a466754bc19247ebe333e1b8b484da2d",
"sha256": "03600015dea5e91a94edf5a6d93888f11508bcfc10ed9552a79714f74fa8bb16"
},
"downloads": -1,
"filename": "pelican_myst_reader-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a466754bc19247ebe333e1b8b484da2d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 24034,
"upload_time": "2024-05-01T18:18:33",
"upload_time_iso_8601": "2024-05-01T18:18:33.058324Z",
"url": "https://files.pythonhosted.org/packages/98/32/b4e391aabc9e01432d9d01601b1fbdd82ee0bf51d823678f04f30ab784d3/pelican_myst_reader-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7101503463a7a4c396944b632005177b5dbdbbca0c109f22a229b062e479aebd",
"md5": "6b3b03fa8227067862f7fbbe2d5f38f6",
"sha256": "cd33b0c9469669b9a96ca0272966e5bfeb4d4c13310d08402863aaf0cc8ddcbe"
},
"downloads": -1,
"filename": "pelican_myst_reader-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6b3b03fa8227067862f7fbbe2d5f38f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 25465,
"upload_time": "2024-05-01T18:18:35",
"upload_time_iso_8601": "2024-05-01T18:18:35.626925Z",
"url": "https://files.pythonhosted.org/packages/71/01/503463a7a4c396944b632005177b5dbdbbca0c109f22a229b062e479aebd/pelican_myst_reader-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 18:18:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ashwinvis",
"github_project": "myst-reader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-myst-reader"
}
JSON
