How can I write comments in the metadata section of a Pelican markdown post?

Question

In Pelican, is it possible to add a comment in the metadata section of a markdown file? Suppose I have a post that looks like this:

Title: Hello World!
Tags: greetings
Date: 2020-01-01

Lorem ipsum sit dolor amet...

Is it possible to add comments to the metadata? For example:

Title: Hello World!
Tags: greetings
Date: 2020-01-01  # This is the first comment.
# This is another comment.

Lorem ipsum sit dolor amet...

The example above does not work because Pelican treats # This is another comment. as a Markdown heading.

How can I comment within the metadata section of Pelican markdown files?

Answer 1

For Markdown content, Pelican delegates processing to the Python-Markdown library. Markdown meta-data is handled by its Meta-Data extension, which I do not believe supports comments within meta-data fields. A cursory examination of tracker issues did not yield any issues related to this question.

In short, this question does not relate to Pelican itself, but instead to the dependent Python-Markdown library.

Answer 2

Use HTML comments instead, or have the comment as "official" metadata. So #1:

Title: Hello World!
Tags: greetings
Date: 2020-01-01  # This is the first comment.
<!-- This is another comment. -->

Lorem ipsum sit dolor amet...

Or #2:

Title: Hello World!
Tags: greetings
Date: 2020-01-01  # This is the first comment.
Comment: This is another comment.

Lorem ipsum sit dolor amet...

Answer 3

There are a number of Pelican plugins you can use that allow the metadata section to be written in YAML, which is (mostly) backwards-compatible with the simple key–value metadata pairs that Pelican expects by default. Examples of these YAML plugins include the following:

• pelican-yaml-metadata
• pelican-md-metayaml
• pelican-frontmark

In YAML, comments start with a # (anywhere on a line, not just at the beginning) and continue to the end of the line, just like in your examples.

There are just a couple things you'll need to keep in mind. First, these plugins require you to begin and end the entire metadata header with lines containing nothing but ---, so if you're converting an existing Pelican site, you may want to write a short script (using sed, Perl, etc.) to add these delimiters to your files. Second, a few other characters in YAML have special meanings, so if you use any of these in your metadata values, you'll need to escape them or wrap the values in single or double quotes.