Are you a Pelican user looking to convert documents written in Pandoc’s variant of Markdown into HTML? Look no further! The Pandoc Reader plugin for Pelican is here to simplify the process for you.
Installation Requirements
Before diving into the installation process, ensure that you have Python 3.8 or higher and Pandoc 2.11 or higher installed on your system. If you’re missing any of these requirements, you can find installation instructions for Pandoc at https://pandoc.org/installing.html.
To install the Pandoc Reader plugin, simply run the following command:
#
python -m pip install pelican-pandoc-reader
Configuring the Plugin
Once installed, you can configure the plugin to meet your needs. Pandoc Reader supports a variety of features and options, including file metadata, Pandoc options, table of contents generation, citations, reading time calculation, and customizing the path for the Pandoc executable.
File Metadata
Pandoc Reader expects all Markdown files to start with a YAML-formatted content header that contains metadata such as the title, author, and date of the post. This is different from Pelican’s front-matter format. If you are currently using Pelican’s front matter format, there is a script available that can convert it to Pandoc’s YAML header format.
For more information on Pandoc’s YAML metadata block and Pelican’s default metadata format, please refer to the links provided in the README.
Pandoc Options
You can pass options to Pandoc through two methods: via Pelican settings or using Pandoc defaults files.
-
Via Pelican Settings
In your Pelican settings file (e.g.,
pelicanconf.py), you can specify arguments supported by Pandoc in thePANDOC_ARGSsetting. You can also enable/disable Pandoc extensions using thePANDOC_EXTENSIONSsetting. -
Using Pandoc Defaults Files
Another method is to specify one or more Pandoc defaults files, which contain YAML-formatted preferences. These paths should be set in your Pelican settings file using the
PANDOC_DEFAULTS_FILESsetting.Using defaults files allows you to use various Markdown variants supported by Pandoc, such as CommonMark and GitHub-Flavored Markdown.
For a more detailed example of a Pandoc defaults file, refer to the README.
Table of Contents Generation
To create a table of contents for your posts or pages, you can specify the --toc or --table-of-contents argument in the PANDOC_ARGS setting. Alternatively, you can add a table-of-contents field with the value set to true in a Pandoc defaults file.
You can then use the {{ article.toc }} or {{ page.toc }} template variables to include the table of contents in your templates.
Citations
If you want to enable citations, you can do so by specifying the -C or --citeproc option. You can set the required options in your Pelican settings file. It is important to note that you must name the bibliography file the same as your post and place it in the same directory or a subdirectory of your blog’s directory.
For more details on enabling citations and known issues, please consult the README.
Reading Time Calculation
Pandoc Reader can calculate the estimated reading time of your articles and pages. By setting CALCULATE_READING_TIME to True in your Pelican settings file, you can enable this feature.
The estimated reading time can be displayed using the {{ article.reading_time }} or {{ page.reading_time }} template variables. The default reading speed is set to 200 words per minute but can be customized by changing the READING_SPEED setting.
Customizing the Path for the Pandoc Executable
If your pandoc executable is not on your PATH, you can specify the absolute path using the PANDOC_EXECUTABLE_PATH setting in your Pelican settings file. This is useful when using a non-standard location for the Pandoc executable.
Contributing
If you’re interested in contributing to the Pandoc Reader plugin, your help is much appreciated! You can contribute by improving the documentation, adding missing features, fixing bugs, or reviewing and commenting on existing issues. Please refer to the README for more information on how to contribute.
Special thanks to Justin Mayer, Erwin Janssen, Joseph Reagle, and Deniz Turgut for their valuable contributions and feedback on this plugin.
Conclusion
The Pandoc Reader plugin for Pelican simplifies the conversion of Pandoc’s variant of Markdown into HTML. With features like file metadata, Pandoc options, table of contents generation, citations, reading time calculation, and more, this plugin has everything you need to enhance your Pelican experience.
If you have any questions, please feel free to ask. Happy coding!
Leave a Reply