Pandoc Reader: A Plugin for Pelican
===================================
[](https://github.com/pelican-plugins/pandoc-reader/actions)
[](https://pypi.org/project/pelican-pandoc-reader/)
Pandoc Reader is a [Pelican][] plugin that converts documents written in [Pandoc’s variant of Markdown][] into HTML.
Requirements
------------
This plugin requires:
* Python 3.8 or higher; and
* Pandoc 2.11 or higher [[Pandoc installation instructions](https://pandoc.org/installing.html)].
By default, the plugin looks for a `pandoc` executable on your `PATH`. If you wish, [you may specify an alternative location for your `pandoc` executable](#customizing-the-path-for-the-pandoc-executable).
Installation
------------
This plugin can be installed via:
```bash
python -m pip install pelican-pandoc-reader
```
Configuration
-------------
This plugin converts [Pandoc’s variant of Markdown][] into HTML. Conversion from other Markdown variants is supported but requires the use of a [Pandoc defaults file](https://pandoc.org/MANUAL.html#defaults-files).
Converting to output formats other than HTML is not supported.
### Specifying 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>"
data: "<date>"
---
```
… or …
```yaml
---
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 to [Python-Markdown’s Meta-Data format](https://python-markdown.github.io/extensions/meta_data/).
If you have files that use Pelican's front matter format, there is a script written by [Joseph Reagle](https://github.com/reagle) available that [converts Pelican's front matter to Pandoc's YAML header format](https://gist.github.com/reagle/5bc44ba9e2f1b961d1aaca9179fb403b).
For more information on Pandoc's YAML metadata block or Pelican's default metadata format please visit the links below:
* [Pandoc’s YAML metadata blocks](https://pandoc.org/MANUAL.html#metadata-blocks)
* [Pelican’s default metadata format](https://docs.getpelican.com/en/stable/content.html#file-metadata)
### Specifying Pandoc Options
The plugin supports two **mutually exclusive** methods for passing options to Pandoc.
#### Method One: Via Pelican Settings
The first method involves configuring two settings in your Pelican settings file (e.g., `pelicanconf.py`):
* `PANDOC_ARGS`
* `PANDOC_EXTENSIONS`
In the `PANDOC_ARGS` setting, you may specify any arguments supported by Pandoc, as shown below:
```python
PANDOC_ARGS = [
"--mathjax",
"--citeproc",
]
```
In the `PANDOC_EXTENSIONS` setting, you may enable/disable any number of the supported [Pandoc extensions](https://pandoc.org/MANUAL.html#extensions):
```python
PANDOC_EXTENSIONS = [
"+footnotes", # Enabled extension
"-pipe_tables", # Disabled extension
]
```
#### Method Two: Using Pandoc Defaults Files
The second method involves specifying the path(s) to one or more [Pandoc defaults files][], with all your preferences written in YAML format.
These paths should be set in your Pelican settings file by using the setting `PANDOC_DEFAULTS_FILES`. The paths may be absolute or relative, but relative paths are recommended as they are more portable.
```python
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:
```yaml
reader: markdown
writer: html5
```
Using defaults files has the added benefit of allowing you to use other Markdown variants supported by Pandoc, such as [CommonMark](https://commonmark.org/) and [GitHub-Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github).
Please see [Pandoc defaults files][] for a more complete example.
> ⚠️ **Note:** Neither method supports the `--standalone` or `--self-contained` arguments, which will yield an error if invoked.
### Generating a Table of Contents
If you want to create a table of contents (ToC) for posts or pages, you may do so by specifying the `--toc` or `--table-of-contents` argument in the `PANDOC_ARGS` setting, as shown below:
```python
PANDOC_ARGS = [
"--toc",
]
```
… or …
```python
PANDOC_ARGS = [
"--table-of-contents",
]
```
To add a ToC via a Pandoc defaults file, use the syntax below:
```yaml
table-of-contents: true
```
The table of contents will be available for use in templates using the `{{ article.toc }}` or `{{ page.toc }}` Jinja template variables.
### Enabling Citations
You may enable citations by specifying the `-C` or `--citeproc` option.
Set the `PANDOC_ARGS` and `PANDOC_EXTENSIONS` in your Pelican settings file as shown below:
```python
PANDOC_ARGS = [
"--citeproc",
]
```
… or …
```python
PANDOC_ARGS = [
"-C",
]
```
If you are using a Pandoc defaults file, you need the following as a bare minimum to enable citations:
```yaml
reader: markdown
writer: html5
citeproc: true
```
Without these settings, citations will not be processed by the plugin.
It is not necessary to specify the `+citations` extension since it is enabled by default. However, if you were to disable citations by specifying `-citations` in `PANDOC_EXTENSIONS` or by setting `reader: markdown-citations` in your defaults file, citations will **not** work.
You may write your bibliography in any format supported by Pandoc with the appropriate extensions specified. However, you **must** name the bibliography file the same as your post.
For example, a post with the file name `my-post.md` should have a bibliography file called `my-post.bib`, `my-post.json`, `my-post.yaml` or `my-post.bibtex` in 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 Citations
If enabling citations with a specific style, you need to specify a CSL (Citation Style Language) file, available from the [Zotero Style Repository](https://www.zotero.org/styles). For example, if you are using `ieee-with-url` style file, it may be specified in your Pelican settings file, as shown below:
```python
PANDOC_ARGS = [
"--csl=https://www.zotero.org/styles/ieee-with-url",
]
```
Or in a Pandoc defaults file:
```yaml
csl: "https://www.zotero.org/styles/ieee-with-url"
```
Specifying a *remote* (that is, not local) CSL file as shown above dramatically increases the time taken to process Markdown content. To improve processing speed, it is _highly_ recommended 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:
```python
PANDOC_ARGS = [
"--csl=path/to/file/ieee-with-url.csl",
]
```
Or in a Pandoc defaults file:
```yaml
csl: "path/to/file/ieee-with-url.csl"
```
### Calculating and Displaying Reading Times
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 of 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 [wordcount Lua Filter](https://github.com/pandoc/lua-filters/tree/master/wordcount).
### Customizing the Path for the `pandoc` Executable
If your `pandoc` executable does not reside on your `PATH`, set the `PANDOC_EXECUTABLE_PATH` in your Pelican settings file to the absolute path of where your `pandoc` resides as shown below:
```python
PANDOC_EXECUTABLE_PATH = /path/to/my/pandoc
```
This setting is useful in cases where the `pandoc` executable 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.
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 [Justin Mayer](https://justinmayer.com), [Erwin Janssen](https://github.com/ErwinJanssen), [Joseph Reagle](https://github.com/reagle) and [Deniz Turgut](https://github.com/avaris) for their improvements and feedback on this plugin.
[existing issues]: https://github.com/pelican-plugins/pandoc-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
[Pandoc’s variant of Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown
[Pandoc defaults files]: https://pandoc.org/MANUAL.html#default-files
Raw data
{
"_id": null,
"home_page": "https://github.com/pelican-plugins/pandoc-reader",
"name": "pelican-pandoc-reader",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0",
"maintainer_email": "",
"keywords": "pelican,plugin,markdown,pandoc",
"author": "Nandakumar Chandrasekhar",
"author_email": "navanitachora@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/76/0d/c52ccef9203763b132b6dfb875cf7b18e3b6c5b39af3cbe4d062f384117c/pelican_pandoc_reader-2.1.0.tar.gz",
"platform": null,
"description": "Pandoc Reader: A Plugin for Pelican\n===================================\n\n[](https://github.com/pelican-plugins/pandoc-reader/actions)\n[](https://pypi.org/project/pelican-pandoc-reader/)\n\n\nPandoc Reader is a [Pelican][] plugin that converts documents written in [Pandoc\u2019s variant of Markdown][] into HTML.\n\nRequirements\n------------\n\nThis plugin requires:\n\n* Python 3.8 or higher; and\n* Pandoc 2.11 or higher [[Pandoc installation instructions](https://pandoc.org/installing.html)].\n\nBy default, the plugin looks for a `pandoc` executable on your `PATH`. If you wish, [you may specify an alternative location for your `pandoc` executable](#customizing-the-path-for-the-pandoc-executable).\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n```bash\npython -m pip install pelican-pandoc-reader\n```\n\nConfiguration\n-------------\n\nThis plugin converts [Pandoc\u2019s variant of Markdown][] into HTML. Conversion from other Markdown variants is supported but requires the use of a [Pandoc defaults file](https://pandoc.org/MANUAL.html#defaults-files).\n\nConverting to output formats other than HTML is not supported.\n\n### Specifying 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>\"\ndata: \"<date>\"\n---\n```\n\n\u2026 or \u2026\n\n```yaml\n---\ntitle: \"<post-title>\"\nauthor: \"<author-name>\"\ndate: \"<date>\"\n...\n```\n\n> \u26a0\ufe0f **Note:** The YAML-formatted header shown above is syntax specific to Pandoc for specifying content metadata. This is different from Pelican\u2019s front-matter format. If you ever decide to stop using this plugin and switch to Pelican\u2019s default Markdown handling, you may need to switch your front-matter metadata to [Python-Markdown\u2019s Meta-Data format](https://python-markdown.github.io/extensions/meta_data/).\n\nIf you have files that use Pelican's front matter format, there is a script written by [Joseph Reagle](https://github.com/reagle) available that [converts Pelican's front matter to Pandoc's YAML header format](https://gist.github.com/reagle/5bc44ba9e2f1b961d1aaca9179fb403b).\n\nFor more information on Pandoc's YAML metadata block or Pelican's default metadata format please visit the links below:\n\n* [Pandoc\u2019s YAML metadata blocks](https://pandoc.org/MANUAL.html#metadata-blocks)\n* [Pelican\u2019s default metadata format](https://docs.getpelican.com/en/stable/content.html#file-metadata)\n\n### Specifying Pandoc Options\n\nThe plugin supports two **mutually exclusive** methods for passing options to Pandoc.\n\n#### Method One: Via Pelican Settings\n\nThe first method involves configuring two settings in your Pelican settings file (e.g., `pelicanconf.py`):\n\n* `PANDOC_ARGS`\n* `PANDOC_EXTENSIONS`\n\nIn the `PANDOC_ARGS` setting, you may specify any arguments supported by Pandoc, as shown below:\n\n```python\nPANDOC_ARGS = [\n \"--mathjax\",\n \"--citeproc\",\n]\n```\n\nIn the `PANDOC_EXTENSIONS` setting, you may enable/disable any number of the supported [Pandoc extensions](https://pandoc.org/MANUAL.html#extensions):\n\n```python\nPANDOC_EXTENSIONS = [\n \"+footnotes\", # Enabled extension\n \"-pipe_tables\", # Disabled extension\n]\n```\n\n#### Method Two: Using Pandoc Defaults Files\n\nThe second method involves specifying the path(s) to one or more [Pandoc defaults files][], with all your preferences written in YAML format.\n\nThese paths should be set in your Pelican settings file by using the setting `PANDOC_DEFAULTS_FILES`. The paths may be absolute or relative, but relative paths are recommended as they are more portable.\n\n```python\nPANDOC_DEFAULTS_FILES = [\n \"<path/to/defaults/file_one.yaml>\",\n \"<path/to/defaults/file_two.yaml>\",\n]\n```\n\nHere is a minimal example of content that should be available in a Pandoc defaults file:\n\n```yaml\nreader: markdown\nwriter: html5\n```\n\nUsing defaults files has the added benefit of allowing you to use other Markdown variants supported by Pandoc, such as [CommonMark](https://commonmark.org/) and [GitHub-Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github).\n\nPlease see [Pandoc defaults files][] for a more complete example.\n\n> \u26a0\ufe0f **Note:** Neither method supports the `--standalone` or `--self-contained` arguments, which will yield an error if invoked.\n\n### Generating a Table of Contents\n\nIf you want to create a table of contents (ToC) for posts or pages, you may do so by specifying the `--toc` or `--table-of-contents` argument in the `PANDOC_ARGS` setting, as shown below:\n\n```python\nPANDOC_ARGS = [\n \"--toc\",\n]\n```\n\n\u2026\u00a0or \u2026\n\n```python\nPANDOC_ARGS = [\n \"--table-of-contents\",\n]\n```\n\nTo add a ToC via a Pandoc defaults file, use the syntax below:\n\n```yaml\ntable-of-contents: true\n```\n\nThe table of contents will be available for use in templates using the `{{ article.toc }}` or `{{ page.toc }}` Jinja template variables.\n\n### Enabling Citations\n\nYou may enable citations by specifying the `-C` or `--citeproc` option.\n\nSet the `PANDOC_ARGS` and `PANDOC_EXTENSIONS` in your Pelican settings file as shown below:\n\n```python\nPANDOC_ARGS = [\n \"--citeproc\",\n]\n```\n\n\u2026 or \u2026\n\n```python\nPANDOC_ARGS = [\n \"-C\",\n]\n```\n\nIf you are using a Pandoc defaults file, you need the following as a bare minimum to enable citations:\n\n```yaml\nreader: markdown\nwriter: html5\n\nciteproc: true\n```\n\nWithout these settings, citations will not be processed by the plugin.\n\nIt is not necessary to specify the `+citations` extension since it is enabled by default. However, if you were to disable citations by specifying `-citations` in `PANDOC_EXTENSIONS` or by setting `reader: markdown-citations` in your defaults file, citations will **not** work.\n\nYou may write your bibliography in any format supported by Pandoc with the appropriate extensions specified. However, you **must** name the bibliography file the same as your post.\n\nFor example, a post with the file name `my-post.md` should have a bibliography file called `my-post.bib`, `my-post.json`, `my-post.yaml` or `my-post.bibtex` in 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.\n\n#### Known Issues with Citations\n\nIf enabling citations with a specific style, you need to specify a CSL (Citation Style Language) file, available from the [Zotero Style Repository](https://www.zotero.org/styles). For example, if you are using `ieee-with-url` style file, it may be specified in your Pelican settings file, as shown below:\n\n```python\nPANDOC_ARGS = [\n \"--csl=https://www.zotero.org/styles/ieee-with-url\",\n]\n```\n\nOr in a Pandoc defaults file:\n\n```yaml\ncsl: \"https://www.zotero.org/styles/ieee-with-url\"\n```\n\nSpecifying a *remote* (that is, not local) CSL file as shown above dramatically increases the time taken to process Markdown content. To improve processing speed, it is _highly_ recommended that you use a local copy of the CSL file downloaded from Zotero.\n\nYou may then reference it in your Pelican settings file as shown below:\n\n```python\nPANDOC_ARGS = [\n \"--csl=path/to/file/ieee-with-url.csl\",\n]\n```\n\nOr in a Pandoc defaults file:\n\n```yaml\ncsl: \"path/to/file/ieee-with-url.csl\"\n```\n\n### Calculating and Displaying Reading Times\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 of 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 [wordcount Lua Filter](https://github.com/pandoc/lua-filters/tree/master/wordcount).\n\n### Customizing the Path for the `pandoc` Executable\n\nIf your `pandoc` executable does not reside on your `PATH`, set the `PANDOC_EXECUTABLE_PATH` in your Pelican settings file to the absolute path of where your `pandoc` resides as shown below:\n\n```python\nPANDOC_EXECUTABLE_PATH = /path/to/my/pandoc\n```\n\nThis setting is useful in cases where the `pandoc` executable from your hosting provider is not recent enough, and you may need to install a version of Pandoc-compatible with this plugin\u2014in a non-standard location.\n\nContributing\n------------\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 [Justin Mayer](https://justinmayer.com), [Erwin Janssen](https://github.com/ErwinJanssen), [Joseph Reagle](https://github.com/reagle) and [Deniz Turgut](https://github.com/avaris) for their improvements and feedback on this plugin.\n\n[existing issues]: https://github.com/pelican-plugins/pandoc-reader/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nLicense\n-------\n\nThis project is licensed under the AGPL-3.0 license.\n\n[Pelican]: https://getpelican.com\n[Pandoc\u2019s variant of Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown\n[Pandoc defaults files]: https://pandoc.org/MANUAL.html#default-files\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Pelican plugin for converting Pandoc's Markdown variant to HTML.",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://docs.getpelican.com",
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/pandoc-reader",
"Issue Tracker": "https://github.com/pelican-plugins/pandoc-reader/issues",
"Repository": "https://github.com/pelican-plugins/pandoc-reader"
},
"split_keywords": [
"pelican",
"plugin",
"markdown",
"pandoc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9052c861d05169895ec04335c8aa20625f7d09de85b70bf2b99d36d1aa77e722",
"md5": "cef44fb8a8a77f1e609da50b9f460871",
"sha256": "6ed3fc4c6dd288e620e236945fdc01ab69b22f4ad2bae4e16ec02328ad1814b8"
},
"downloads": -1,
"filename": "pelican_pandoc_reader-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cef44fb8a8a77f1e609da50b9f460871",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0",
"size": 42662,
"upload_time": "2023-11-23T05:17:17",
"upload_time_iso_8601": "2023-11-23T05:17:17.351902Z",
"url": "https://files.pythonhosted.org/packages/90/52/c861d05169895ec04335c8aa20625f7d09de85b70bf2b99d36d1aa77e722/pelican_pandoc_reader-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "760dc52ccef9203763b132b6dfb875cf7b18e3b6c5b39af3cbe4d062f384117c",
"md5": "ff033807dda041b4e922c1e1d5476c12",
"sha256": "a6cf9b469972ae2d109a13de74b4cdf9e9022904dc0b8f91a200e56537061e1d"
},
"downloads": -1,
"filename": "pelican_pandoc_reader-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ff033807dda041b4e922c1e1d5476c12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0",
"size": 23703,
"upload_time": "2023-11-23T05:17:20",
"upload_time_iso_8601": "2023-11-23T05:17:20.284075Z",
"url": "https://files.pythonhosted.org/packages/76/0d/c52ccef9203763b132b6dfb875cf7b18e3b6c5b39af3cbe4d062f384117c/pelican_pandoc_reader-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 05:17:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "pandoc-reader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-pandoc-reader"
}
JSON
