Package: pelican-myst-reader
MyST Reader: A Plugin for PelicanMyST Readeris aPelicanplugin that converts documents written inMyST’s variant of Markdowninto HTML.RequirementsThis plugin requires:Python 3.9 or higherInstallationThis plugin can be installed via:python-mpipinstallpelican-myst-readerAs 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 contentMyST syntax is a superset ofCommonMark. 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 withMyST syntaxto get access to more features. You can play with theMyST live previewto see what is possible.File MetadataThe plugin expects all Markdown files to start with a YAML-formatted content header, as shown below.---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 theFORMATTED_FIELDSlist variable inpelicanconf.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 toPython-Markdown’s Meta-Data
format.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.---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 formatConfigurationThe 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 RendererBy default MyST rely onDocutilsto parse and render its syntax. That'sbecause MyST primarily targets Sphinx.To produce HTML for Pelican,MyST Readeruses Docutils too (and more precisely itsHTML5 Writer).This plugin setup Docutils with good settings by defaults. But you can still influence it
with theMYST_DOCUTILS_SETTINGSsetting.Here is an example of configuration inpelicanconf.py: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 theMYST_DOCUTILS_SETTINGSsetting is used to pass both:Docutils configurationMyST parser configuration, includingAlso notice how:MyST-specific settings are prefixed withmyst_the list of additionalMyST extensionsto activate is set withmyst_enable_extensions⚠️Note:MYST_DOCUTILS_SETTINGSaccepts the same parameters asPelican’sDOCUTILS_SETTINGS. We could have reused them but wedecided to keep them separatefor clarity.Sphinx RendererMyST Readeralso supports an alternative rendering mode usingSphinx.You can force this rendering mode for all files with: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 toFalse, 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 (dollarmathoramsmath) inMYST_SPHINX_SETTINGSBibTeX files are foundNow this rendering mode also has its own dedicated configuration setting:MYST_SPHINX_SETTINGS. It is a dictionary that will be used to build aconf.pyfile to be passed to the Sphinx builder.Here is an example of configuration inpelicanconf.py: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 configurationMyST parser configurationAnd again:MyST-specific settings are prefixed withmyst_the list of additionalMyST extensionsto activate is set withmyst_enable_extensionsDeprecatedMYST_EXTENSIONSThere is a dedicatedMYST_EXTENSIONSsetting to activate MyST extensions. But it is deprecated in favor of theMYST_DOCUTILS_SETTINGS["myst_enable_extensions"]andMYST_SPHINX_SETTINGS["myst_enable_extensions"]settings.It is still loaded up byMyST Readerfor backward compatibility but will be ignored in a future release.IfMYST_EXTENSIONSis set, it will be used to populateMYST_DOCUTILS_SETTINGS["myst_enable_extensions"]andMYST_SPHINX_SETTINGS["myst_enable_extensions"].Reading TimeThis plugin may be used to calculate the estimated reading time of articles and pages by settingCALCULATE_READING_TIMEtoTruein your Pelican settings file:CALCULATE_READING_TIME=TrueYou 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 settingREADING_SPEEDto the desired words per minute value in your Pelican settings file:READING_SPEED=<words-per-minute>The number of words in a document is calculated using theMarkdown Word Countpackage.LimitationsThis plugin convertsMyST’s variant of Markdowninto HTML for Pelican. MyST being a
superset ofCommonMarkshould cover most Markdown variants. But
strictly speaking, conversion from other Markdown variants is unsupported.Converting to output formats other than HTML is also unsupported.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.Special thanks toJustin Mayer,Erwin Janssen,Joseph ReagleandDeniz Turgutfor their improvements and feedback on this plugin.LicenseThis project is licensed under the AGPL-3.0 license.