Package: pelican-pandoc-reader
Pandoc Reader: A Plugin for PelicanPandoc Reader is aPelicanplugin that converts documents written inPandoc’s variant of Markdowninto HTML.RequirementsThis plugin requires:Python 3.8 or higher; andPandoc 2.11 or higher [Pandoc installation instructions].By default, the plugin looks for apandocexecutable on yourPATH. If you wish,you may specify an alternative location for yourpandocexecutable.InstallationThis plugin can be installed via:python-mpipinstallpelican-pandoc-readerConfigurationThis plugin convertsPandoc’s variant of Markdowninto HTML. Conversion from other Markdown variants is supported but requires the use of aPandoc defaults file.Converting to output formats other than HTML is not supported.Specifying File MetadataThe plugin expects all Markdown files to start with a YAML-formatted content header, as shown below.---title:"<post-title>"author:"<author-name>"data:"<date>"---… or …---title:"<post-title>"author:"<author-name>"date:"<date>"...⚠️Note:The YAML-formatted header shown above is syntax specific to Pandoc for specifying content metadata. This is 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.If you have files that use Pelican's front matter format, there is a script written byJoseph Reagleavailable thatconverts Pelican's front matter to Pandoc's YAML header format.For more information on Pandoc's YAML metadata block or Pelican's default metadata format please visit the links below:Pandoc’s YAML metadata blocksPelican’s default metadata formatSpecifying Pandoc OptionsThe plugin supports twomutually exclusivemethods for passing options to Pandoc.Method One: Via Pelican SettingsThe first method involves configuring two settings in your Pelican settings file (e.g.,pelicanconf.py):PANDOC_ARGSPANDOC_EXTENSIONSIn thePANDOC_ARGSsetting, you may specify any arguments supported by Pandoc, as shown below:PANDOC_ARGS=["--mathjax","--citeproc",]In thePANDOC_EXTENSIONSsetting, you may enable/disable any number of the supportedPandoc extensions:PANDOC_EXTENSIONS=["+footnotes",# Enabled extension"-pipe_tables",# Disabled extension]Method Two: Using Pandoc Defaults FilesThe second method involves specifying the path(s) to one or morePandoc defaults files, with all your preferences written in YAML format.These paths should be set in your Pelican settings file by using the settingPANDOC_DEFAULTS_FILES. The paths may be absolute or relative, but relative paths are recommended as they are more portable.PANDOC_DEFAULTS_FILES=["<path/to/defaults/file_one.yaml>","<path/to/defaults/file_two.yaml>",]Here is a minimal example of content that should be available in a Pandoc defaults file:reader:markdownwriter:html5Using defaults files has the added benefit of allowing you to use other Markdown variants supported by Pandoc, such asCommonMarkandGitHub-Flavored Markdown.Please seePandoc defaults filesfor a more complete example.⚠️Note:Neither method supports the--standaloneor--self-containedarguments, which will yield an error if invoked.Generating a Table of ContentsIf you want to create a table of contents (ToC) for posts or pages, you may do so by specifying the--tocor--table-of-contentsargument in thePANDOC_ARGSsetting, as shown below:PANDOC_ARGS=["--toc",]… or …PANDOC_ARGS=["--table-of-contents",]To add a ToC via a Pandoc defaults file, use the syntax below:table-of-contents:trueThe table of contents will be available for use in templates using the{{ article.toc }}or{{ page.toc }}Jinja template variables.Enabling CitationsYou may enable citations by specifying the-Cor--citeprocoption.Set thePANDOC_ARGSandPANDOC_EXTENSIONSin your Pelican settings file as shown below:PANDOC_ARGS=["--citeproc",]… or …PANDOC_ARGS=["-C",]If you are using a Pandoc defaults file, you need the following as a bare minimum to enable citations:reader:markdownwriter:html5citeproc:trueWithout these settings, citations will not be processed by the plugin.It is not necessary to specify the+citationsextension since it is enabled by default. However, if you were to disable citations by specifying-citationsinPANDOC_EXTENSIONSor by settingreader: markdown-citationsin your defaults file, citations willnotwork.You may write your bibliography in any format supported by Pandoc with the appropriate extensions specified. However, youmustname the bibliography file the same as your post.For example, a post with the file namemy-post.mdshould have a bibliography file calledmy-post.bib,my-post.json,my-post.yamlormy-post.bibtexin the same directory as your post, or in a subdirectory of the directory that your blog resides in. Failure to do so will prevent the references from being picked up.Known Issues with CitationsIf enabling citations with a specific style, you need to specify a CSL (Citation Style Language) file, available from theZotero Style Repository. For example, if you are usingieee-with-urlstyle file, it may be specified in your Pelican settings file, as shown below:PANDOC_ARGS=["--csl=https://www.zotero.org/styles/ieee-with-url",]Or in a Pandoc defaults file:csl:"https://www.zotero.org/styles/ieee-with-url"Specifying aremote(that is, not local) CSL file as shown above dramatically increases the time taken to process Markdown content. To improve processing speed, it ishighlyrecommended that you use a local copy of the CSL file downloaded from Zotero.You may then reference it in your Pelican settings file as shown below:PANDOC_ARGS=["--csl=path/to/file/ieee-with-url.csl",]Or in a Pandoc defaults file:csl:"path/to/file/ieee-with-url.csl"Calculating and Displaying Reading TimesThis 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 of 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 thewordcount Lua Filter.Customizing the Path for thepandocExecutableIf yourpandocexecutable does not reside on yourPATH, set thePANDOC_EXECUTABLE_PATHin your Pelican settings file to the absolute path of where yourpandocresides as shown below:PANDOC_EXECUTABLE_PATH=/path/to/my/pandocThis setting is useful in cases where thepandocexecutable from your hosting provider is not recent enough, and you may need to install a version of Pandoc-compatible with this plugin—in a non-standard location.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.