Fine Tuning Pelican: Markdown Configuration

Preface¶

This is one of the articles in a series about how I fine tuned my Pelican+Elegant web site to make it “more mine”. For other articles in the series, click on the title of the article under the heading “Fine Tuning Pelican” on the right side of the webpage.

Unlike my series on Choosing and Setting Up Pelican, these articles are intended to be byte sized, addressing specific fine tunings I made to my own website. As such, the first article in this series contains a Disclaimer section with generic information for each of the articles in the series.

Introduction¶

When choosing authoring tools for a website, a primary concern is that the tools are either already used by the authors or easy enough to learn by the authors that it does not allow them to write freely. For me, I regularly author documentation in Markdown using Visual Studio Code for my professional job, so using the same tools for my website was an easy choice. However, unlike the documents I write at work, the Pelican generator utilizes the Python-Markdown generator library which has a few more options than standard Markdown. This article details the Markdown configuration that I have enabled for my website, and why I have enabled the specified configuration.

Markdown Configuration¶

The following configuration is the Markdown configuration for my website:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.extra': {},
        'markdown.extensions.admonition': {},
        'markdown.extensions.codehilite': {
            'css_class': 'highlight'
        },
        'markdown.extensions.meta': {},
        'smarty' : {
            'smart_angled_quotes' : 'true'
        },
        'markdown.extensions.toc': {
            'permalink': 'true',
        },
    }
}

markdown.extensions.meta¶

This configuration is perhaps the most important extension that I use. This setting enables the Python-Markdown - Metadata feature which enables the processing of the header of Markdown files with metadata about the Markdown that is being authored. While the Python-Markdown processor does not use this metadata itself, the metadata is passed to Pelican and Elegant to allow for configuration of the articles and pages on a one-by-one basis.

This choice is actually a requirement for Pelican to work, being provided as one of the defaults for the MARKDOWN configuration element, as documented here.

markdown.extensions.extra¶

This configuration enables the Python-Markdown - Extra features which includes support for: abbreviations, attribute lists, definition lists, fenced code blocks, footnotes, and tables.

This choice is actually a requirement for Pelican to work, being provided as one of the defaults for the MARKDOWN configuration element, as documented here.

markdown.extensions.codehilite¶

This configuration enables the Python-Markdown - Code Hilites feature to provide for special displaying of marked text within given areas of the document. These sections or specially marked text are typically used to display text that represents code for programs or scripts, with more stringent rules on how to display the text.

If no specific text format is specified with the text block, such as many of the code blocks in the article on Static Websites: Posting My First Article. If a text format is specified, this feature will try it’s best to match it to known highlighters, using color to indicate different parts of the specified text format. This can be seen in a later section of the above article where a code block is used for a sample Markdown article and later in the series where Python configuration is referenced. In both of these examples, the highlighting done to the text is able to be changed according to the type of text being highlighted.

This choice is actually a requirement for Pelican to work, being provided as one of the defaults for the MARKDOWN configuration element, as documented here.

markdown.extensions.toc¶

This configuration is present as part of the setup for Elegant’s Table Of Contents support. This specific value instructs the Python-Markdown - Table of Contents feature to generate permanent links at the end of each header. These links provide the destination URLs that Elegant’s Table of Content support use to go directly to a given item in the Table of Contents.

I subscribe to Elegant’s philosophy on providing a clean reading experience with minimal distractions. By moving the table of contents to the left sidebar and out of the article, I believe the reader can focus more on the article.

markdown.extensions.admonition¶

This configuration enables the Python-Markdown - Admonition feature to provide a highlighted box around the indicated text content. These highlighted boxes are themed by Elegant to provide for a good, quick communication of important information to the reader without being too disruptive. An example of admonitions is available in this article on Glanceable Displays.

I find that using admonitions in articles allows me to include more useful and descriptive information to the reader. The options of sections of tests in various parentheses and braces, or placing the text in footnotes, doesn’t feel right to me, while admonitions, with their colored call outs do. This is a personal preference.

smarty¶

This configuration enables the Python-Markdown - SmartyPants feature to provide for more clear representation of various characters and character sequences used in articles and pages.

With this feature enabled, the following substitutions are made:

• the apostrophe character (') is translated into a left and right single quotes around the words or phrases they surround: ‘this is my phrase’
• the quotation character (') is translated into a left and right double quotes around the words or phrases they surround: “this is my phrase”
• double greater than signs (>>) and less than signs (<<) are translated into angled quotes: « and »
• three period characters in a row (...) are translated into ellipses: and so they said…
• two consecutive dashes (--) and three consecutive dashes (---) are turned into lengthened dash characters: – and —

While I am not 100% sold on this one, I like the effects it has, even though they are small. It just seems to add a bit of a finished touch to the articles.

What Was Accomplished¶

This article was created to share the Markdown configuration that I use for my website For each feature that I use I specify what benefit it provides to the articles, along with the reasons that have for using that Markdown feature.

Like this post? Share on: Twitter ❄ Facebook ❄ Email