CommonMark Reader for Pelican
=============================
*Powered by Markdown-IT-Py*
This plugin is intended to be a roughly drop-in replacement for Pelican's
built-in Markdown Reader (the "reader" is the part of Pelican that turns your
source files into something Pelican can assemble into a website). As this uses
a CommonMark implementation of Markdown (specifically, `markdown-it-py
<https://github.com/executablebooks/markdown-it-py>`_, there are be subtle
differences when compared to the output of Pelican's built in Markdown Reader
(which relies on `Python-Markdown <https://python-markdown.github.io/>`_);
if you are particular about your site output, it may require building the site
with the two readers, and running a diff on the two outputs, and tweaking your
source files (or adding Markdown plugins here) until the output is what you
want.
When I set out to build this plugin, I (naively) thought I would stick to a
"pure" CommonMark/Markdown implementation, but I quickly realized that I like
the extensions to Markdown I use, and I wasn't ready to give them up. That
said, I've tried to keep them generally mild. The default configuration will
automatically include all the plugins that I use by default, although you can
add or remove from that list as you wish. Currently enabled CommonMark
extensions are:
- front matter
- footnotes
- defintion list
- tables
Changes Required from "Vanilla" Pelican
---------------------------------------
This (Pelican) plugin uses the Markdown-IT front matter (plugin) by default.
This expects front matter (i.e. metadata) to be at the top of the file, between
lines of three dashes (e.g. ``---``). ("Vanilla" Pelican doesn't require these
marker lines.) Front matter is then phrased as YAML.
An example::
---
title: Front matter Test
Category: test
date: 2023-11-19 14:56
---
This is a test of the front matter plugin.
If you don't want to (or can't) update your source files, you can provide a
customized ``COMMONMARK`` settings (in your ``pelicanconf.py``) that doesn't
include the frontmatter plugin.
If the frontmatter plugin is not active, the plugin should parse metadata in
the same matter as "vanilla" Pelican. Note that this has been less tested, as I
personally use the front matter plugin.
To rely on "vanilla Pelican" front matter (generally, not recommended):
.. code-block:: python
# pelicanconf.py
from minchin.pelican.readers.commonmark.constants import COMMONMARK_DEFAULT_CONFIG
# other Pelican settings
# start with default configuration
COMMONMARK = COMMONMARK_DEFAULT_CONFIG
# add remove Markdown-IT's front matter plugin
for i, plugin in enumerate(COMMONMARK["extensions"]):
if plugin.__name__ == "front_matter_plugin":
del a["extensions"][i]
Additional Features
-------------------
In addition to the "base" CommonMark parser/render, this Reader offers the
following additional features:
- Title from H1: if a post's title isn't defined in the metadata block, it will
try and pull a title from the first H1 tag in the body of the entry.
- Remove duplicated H1 title: If the first H1 tag in the post matches the title
as defined in the metadata block, it will remove the H1 tag. It is assumed
that the theme will include the title as a H1 tag in the generated site.
- Relative links ready for Pelican: relative links included in the body of
posts will have ``{filename}`` or ``{static}`` prefixed to them, so that
Pelican can maintain these links even if the generated site has a different
layout from your source files.
- Code block highlighting: Pygments is called to allow code block syntax
highlighting. Generated site HTML will display code highlighting if you
include (or link to) a Pygments CSS file.
- removes "tag only" lines from the body of your entries.
- "cleans" dates provided in front matter, so they are provided to Pelican as
``datetimes`` rather than strings.
Pelican Settings
----------------
COMMONMARK = {"extensions": [<plugin classes>], "enable": [<str of name of features>]}
(To be defined). Used to configure which CommonMark extensions are loaded by
the plugin. The default is available at
``minchin.pelican.readers.commonmark.constants.COMMONMARK_DEFAULT_CONFIG``.
This is a dictionary, expecting two keys: ``extensions`` and ``enable``, each
with a list as the key. For *extensions*, the list items should be the
classes of the Markdown-IT plugins (aka "extensions") you want to use. For
*enable*, it should be the names (as strings) of the Markdown-IT features you
want to enable (e.g. ``"table"``).
COMMONMARK_VERSION
Version of the plugin. Inserted by the plugin (if not provided).
COMMONMARK_DEV_URL
Homepage URL of the plugin. Inserted by the plugin (if not provided).
COMMONMARK_HTML_PARSER = "html.parser"
Will be set to "lxml" is it is installed. This is the parser that Beautiful
Soup uses.
COMMONMARK_MARKDOWN_LOG_LEVEL = logging.WARNING
If you want to see the debugging for the Markdown-IT library change this to
``logging.DEBUG`` (but be warned that it is *very* verbose).
COMMONMARK_INLINE_TAG_SYMBOLS = "#"
Tag symbols used before inline tags. If a line contains only tags, it will be
removed from the body of the entry.
Extended Abilities
------------------
I have written a *markdown-it-py* plugin to support "fancy"
tasklists/checkboxes, but it is not activated by default.
This requires separate installation and activation within *Pelican*, which you
might do like this:
.. code-block:: python
# pelicanconf.py
from minchin.pelican.readers.commonmark.constants import COMMONMARK_DEFAULT_CONFIG
import minchin.md_it.fancy_tasklists
# other Pelican settings
# start with default configuration
COMMONMARK = COMMONMARK_DEFAULT_CONFIG
# add fancy tasklists
COMMONMARK["extensions"].append(
minchin.md_it.fancy_tasklists.fancy_tasklists_plugin,
)
See `sample rendered checkboxes
<https://github.com/MinchinWeb/seafoam/blob/master/docs/screenshots/2.10.0/fancy-checkboxes.png>`_.
Prior Art
---------
This plugin relies on much work that has gone before, both explicitly for code
and implicitely for the encouragement of this even being possible. This list is
sadly incomplete, but in particlar:
- Johnathan Sundqvist's `Obisidian Plugin for Pelican
<https://github.com/jonathan-s/pelican-obsidian>`_ (and forks) -- in
particular, for providing inspiration on how to deal with Wiki-style links
.. To Implement/Fix
.. ----------------
Raw data
{
"_id": null,
"home_page": null,
"name": "minchin.pelican.readers.commonmark",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": "William Minchin <w_minchin@hotmail.com>",
"keywords": "pelican, plugin",
"author": null,
"author_email": "William Minchin <w_minchin@hotmail.com>, \"Gaige B. Paulsen\" <gaige@cluetrust.com>",
"download_url": "https://files.pythonhosted.org/packages/de/76/f6e8b106cb188d3d8ee521366cc6297b040fedb66a95a512e9f1d5244a99/minchin.pelican.readers.commonmark-2.0.0.tar.gz",
"platform": null,
"description": "CommonMark Reader for Pelican\r\n=============================\r\n\r\n*Powered by Markdown-IT-Py*\r\n\r\nThis plugin is intended to be a roughly drop-in replacement for Pelican's\r\nbuilt-in Markdown Reader (the \"reader\" is the part of Pelican that turns your\r\nsource files into something Pelican can assemble into a website). As this uses\r\na CommonMark implementation of Markdown (specifically, `markdown-it-py\r\n<https://github.com/executablebooks/markdown-it-py>`_, there are be subtle\r\ndifferences when compared to the output of Pelican's built in Markdown Reader\r\n(which relies on `Python-Markdown <https://python-markdown.github.io/>`_);\r\nif you are particular about your site output, it may require building the site\r\nwith the two readers, and running a diff on the two outputs, and tweaking your\r\nsource files (or adding Markdown plugins here) until the output is what you\r\nwant.\r\n\r\nWhen I set out to build this plugin, I (naively) thought I would stick to a\r\n\"pure\" CommonMark/Markdown implementation, but I quickly realized that I like\r\nthe extensions to Markdown I use, and I wasn't ready to give them up. That\r\nsaid, I've tried to keep them generally mild. The default configuration will\r\nautomatically include all the plugins that I use by default, although you can\r\nadd or remove from that list as you wish. Currently enabled CommonMark\r\nextensions are:\r\n\r\n- front matter\r\n- footnotes\r\n- defintion list\r\n- tables\r\n\r\nChanges Required from \"Vanilla\" Pelican\r\n---------------------------------------\r\n\r\nThis (Pelican) plugin uses the Markdown-IT front matter (plugin) by default.\r\nThis expects front matter (i.e. metadata) to be at the top of the file, between\r\nlines of three dashes (e.g. ``---``). (\"Vanilla\" Pelican doesn't require these\r\nmarker lines.) Front matter is then phrased as YAML.\r\n\r\nAn example::\r\n\r\n ---\r\n title: Front matter Test\r\n Category: test\r\n date: 2023-11-19 14:56\r\n ---\r\n\r\n This is a test of the front matter plugin.\r\n\r\nIf you don't want to (or can't) update your source files, you can provide a\r\ncustomized ``COMMONMARK`` settings (in your ``pelicanconf.py``) that doesn't\r\ninclude the frontmatter plugin.\r\n\r\nIf the frontmatter plugin is not active, the plugin should parse metadata in\r\nthe same matter as \"vanilla\" Pelican. Note that this has been less tested, as I\r\npersonally use the front matter plugin.\r\n\r\nTo rely on \"vanilla Pelican\" front matter (generally, not recommended):\r\n\r\n.. code-block:: python\r\n\r\n # pelicanconf.py\r\n\r\n from minchin.pelican.readers.commonmark.constants import COMMONMARK_DEFAULT_CONFIG\r\n\r\n # other Pelican settings\r\n\r\n # start with default configuration\r\n COMMONMARK = COMMONMARK_DEFAULT_CONFIG\r\n # add remove Markdown-IT's front matter plugin\r\n for i, plugin in enumerate(COMMONMARK[\"extensions\"]):\r\n if plugin.__name__ == \"front_matter_plugin\":\r\n del a[\"extensions\"][i]\r\n\r\nAdditional Features\r\n-------------------\r\n\r\nIn addition to the \"base\" CommonMark parser/render, this Reader offers the\r\nfollowing additional features:\r\n\r\n- Title from H1: if a post's title isn't defined in the metadata block, it will\r\n try and pull a title from the first H1 tag in the body of the entry.\r\n- Remove duplicated H1 title: If the first H1 tag in the post matches the title\r\n as defined in the metadata block, it will remove the H1 tag. It is assumed\r\n that the theme will include the title as a H1 tag in the generated site.\r\n- Relative links ready for Pelican: relative links included in the body of\r\n posts will have ``{filename}`` or ``{static}`` prefixed to them, so that\r\n Pelican can maintain these links even if the generated site has a different\r\n layout from your source files.\r\n- Code block highlighting: Pygments is called to allow code block syntax\r\n highlighting. Generated site HTML will display code highlighting if you\r\n include (or link to) a Pygments CSS file.\r\n- removes \"tag only\" lines from the body of your entries.\r\n- \"cleans\" dates provided in front matter, so they are provided to Pelican as\r\n ``datetimes`` rather than strings.\r\n\r\nPelican Settings\r\n----------------\r\n\r\nCOMMONMARK = {\"extensions\": [<plugin classes>], \"enable\": [<str of name of features>]}\r\n (To be defined). Used to configure which CommonMark extensions are loaded by\r\n the plugin. The default is available at\r\n ``minchin.pelican.readers.commonmark.constants.COMMONMARK_DEFAULT_CONFIG``.\r\n\r\n This is a dictionary, expecting two keys: ``extensions`` and ``enable``, each\r\n with a list as the key. For *extensions*, the list items should be the\r\n classes of the Markdown-IT plugins (aka \"extensions\") you want to use. For\r\n *enable*, it should be the names (as strings) of the Markdown-IT features you\r\n want to enable (e.g. ``\"table\"``).\r\n\r\nCOMMONMARK_VERSION\r\n Version of the plugin. Inserted by the plugin (if not provided).\r\n\r\nCOMMONMARK_DEV_URL\r\n Homepage URL of the plugin. Inserted by the plugin (if not provided).\r\n\r\nCOMMONMARK_HTML_PARSER = \"html.parser\"\r\n Will be set to \"lxml\" is it is installed. This is the parser that Beautiful\r\n Soup uses.\r\n\r\nCOMMONMARK_MARKDOWN_LOG_LEVEL = logging.WARNING\r\n If you want to see the debugging for the Markdown-IT library change this to\r\n ``logging.DEBUG`` (but be warned that it is *very* verbose).\r\n\r\nCOMMONMARK_INLINE_TAG_SYMBOLS = \"#\"\r\n Tag symbols used before inline tags. If a line contains only tags, it will be\r\n removed from the body of the entry.\r\n\r\nExtended Abilities\r\n------------------\r\n\r\nI have written a *markdown-it-py* plugin to support \"fancy\"\r\ntasklists/checkboxes, but it is not activated by default.\r\n\r\nThis requires separate installation and activation within *Pelican*, which you\r\nmight do like this:\r\n\r\n.. code-block:: python\r\n\r\n # pelicanconf.py\r\n\r\n from minchin.pelican.readers.commonmark.constants import COMMONMARK_DEFAULT_CONFIG\r\n import minchin.md_it.fancy_tasklists\r\n\r\n # other Pelican settings\r\n\r\n # start with default configuration\r\n COMMONMARK = COMMONMARK_DEFAULT_CONFIG\r\n # add fancy tasklists\r\n COMMONMARK[\"extensions\"].append(\r\n minchin.md_it.fancy_tasklists.fancy_tasklists_plugin,\r\n )\r\n\r\nSee `sample rendered checkboxes\r\n<https://github.com/MinchinWeb/seafoam/blob/master/docs/screenshots/2.10.0/fancy-checkboxes.png>`_.\r\n\r\n\r\nPrior Art\r\n---------\r\n\r\nThis plugin relies on much work that has gone before, both explicitly for code\r\nand implicitely for the encouragement of this even being possible. This list is\r\nsadly incomplete, but in particlar:\r\n\r\n- Johnathan Sundqvist's `Obisidian Plugin for Pelican\r\n <https://github.com/jonathan-s/pelican-obsidian>`_ (and forks) -- in\r\n particular, for providing inspiration on how to deal with Wiki-style links\r\n\r\n.. To Implement/Fix\r\n.. ----------------\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CommonMark Reader for Pelican (via Markdown-IT)",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/MinchinWeb/minchin.pelican.readers.commonmark/issues",
"Changelog": "https://github.com/MinchinWeb/minchin.pelican.readers.commonmark/blob/master/CHANGELOG.rst",
"Repository": "https://github.com/MinchinWeb/minchin.pelican.readers.commonmark"
},
"split_keywords": [
"pelican",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7edb66c5db9e609ec0c82ab9c9d9b458cb7bfe95b3711e699d2bab56e47ea6e",
"md5": "22a89bebc641b58ecd2442241d9087a2",
"sha256": "8e07b0c694c3cece30503eb34c1dd784171f22542d7c06c7b03bdb59c68083ce"
},
"downloads": -1,
"filename": "minchin.pelican.readers.commonmark-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22a89bebc641b58ecd2442241d9087a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16284,
"upload_time": "2024-03-31T02:07:34",
"upload_time_iso_8601": "2024-03-31T02:07:34.646994Z",
"url": "https://files.pythonhosted.org/packages/a7/ed/b66c5db9e609ec0c82ab9c9d9b458cb7bfe95b3711e699d2bab56e47ea6e/minchin.pelican.readers.commonmark-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "de76f6e8b106cb188d3d8ee521366cc6297b040fedb66a95a512e9f1d5244a99",
"md5": "9615de0255fdf1522e5f6799249597eb",
"sha256": "a42aed0e3d5a56a05c9ac7254ba665fbf2ea5ae5bb9e4ed31db0c1cd3fca08e8"
},
"downloads": -1,
"filename": "minchin.pelican.readers.commonmark-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9615de0255fdf1522e5f6799249597eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17194,
"upload_time": "2024-03-31T02:06:52",
"upload_time_iso_8601": "2024-03-31T02:06:52.985664Z",
"url": "https://files.pythonhosted.org/packages/de/76/f6e8b106cb188d3d8ee521366cc6297b040fedb66a95a512e9f1d5244a99/minchin.pelican.readers.commonmark-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 02:06:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MinchinWeb",
"github_project": "minchin.pelican.readers.commonmark",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "minchin.pelican.readers.commonmark"
}
JSON
