Pelican: Improve metadata field documentation

[ghost]

Hello,

I've been experimenting with Pelican for some weeks now. I enjoy it much more than Hugo for several reasons:

• It supports reStructuredText by default.
• Multi-language articles is easy to use, both as a writer and reader.
• The documentation is much clearer and detailed.

Still, I think some things should be reworked in the current documentation. For exemple, on the “Writing content article”:

• It should be clearer about how the “File metadata” syntax to use, depending of the chosen markup style (Markdown, reStructuredText, AsciiDoc)
• A table should list all the available metadata: their name, function, use and if they are mandatory or not.

Other ideas may be posted below this post.

Of course, I'm ready to help with a pull request. Just let me know where is the complete metadata list and I'll submit something to you.

Best regards.

[justinmayer]

Hi @marespiaut. Thank you for the kind words. Glad to hear you are enjoying Pelican. :grin:

It should be clearer about how the “File metadata” syntax to use, depending of the chosen markup style (Markdown, reStructuredText, AsciiDoc)

I believe the existing metadata documentation makes this fairly clear, but I'm open to suggestions. How do you propose improving its clarity?

A table should list all the available metadata: their name, function, use and if they are mandatory or not

I can see how that would be useful and would welcome your contributions to that effect. :smile:

Just let me know where is the complete metadata list and I'll submit something to you.

Other than at the code level, I'm not certain that there is a canonical list available at this time. Of course, it's possible (while not particularly likely) that the metadata fields shown in the aforementioned existing metadata documentation does, in fact, represent the full list.

[jorgesumle]

Of course, it's possible (while not particularly likely) that the metadata fields shown in the aforementioned existing metadata documentation does, in fact, represent the full list.

The lang metadata is missing from that sample.

[avaris]

FYI, #2321

You can add "functions" to those. Most of them will be trivial and self explanatory though. status, template, save_as and url are probably the most special ones that could use some explanation.

[justinmayer]

Hi @marespiaut. Now that there is a list of reserved metadata keywords (see above), would you like to submit your proposed enhancements as you suggested?

[ghost]

Hello @justinmayer,

The only idea I had for the documentation was something that would have looked like this:

Writing content

File metadata

Keywords

reStructuredText | Markdown | Description
---------------- | -------- | -----------
:title: | Title: | Title of the article
:date: | Date: | Writing date of the article. Should always be formated like YYYY-MM-DD HH:SS
:modified: | Modified: | Modification date of the article. Should always be formated like YYYY-MM-DD HH:SS
:tags: | Tags: | Tags of the article. Multiple tags can be set
:keywords: | Keywords: | Keywords of the article. Multiple keywords can be set
:category: | Category: | Category of the article. Only one can be set
:slug: | Slug: | Identifier for the article. This must not be modified between an article and it's translation
:author: | Author: | Author of the article. Only one can be set
:authors: | Authors: | Authors of the article. Multiple can be set
:summary: | Summary: | Short description of the article
:lang: | Lang: | Langage of the article. Only one can be set, like fr, or en, etc.
:translation: | Translation: | If the article is the translated version of another one. Can be true or false
:status: | Status: | Status of the article. Can be draft, hidden, or published

This array is incomplete, but my idea was to concentrate all information into one single spot.

[egberts]

For ":Title:", do we still need to compensate for Pythonization of all numeric titles as integer, by saying "need to add double-quote around all-numeric title"?

Or is that a Markdown-specific issue?

[avaris]

@egberts Umm, what? Title is a string. As far as pelican (or Python) is concerned, you can put whatever you want.

[egberts]

Pelican takes my "Title: 404" and makes a .html file instead of the expected 404.html.

    Title:404
    ...

If I put quotes around the numeric-only title value, like in:

    Title: "404"
    ...

Then it properly creates the filename portion of 404.html file.

Whether it is a bug or we need documentation for this exception; since I cannot answer that question, I filed an issue #2464 .

[egberts]

Edited: Also, for the row that is "Status", the 'hidden' value can only be used with pages and not articles.

[egberts]

For the "Author" and "Authors", only one of the field name can be used.

[egberts]

For the "Date:", it also takes in legacy time format of "2018-11-20T23:22.

[egberts]

I think "Date:" and "Title:" should be marked as "mandatory."

Edited: "Title:" is mandatory, "Date:" is mandatory only for articles.

[avaris]

Also, for the row that is "Status", the 'hidden' value can only be used with Articles and not pages.

The other way around. It's for pages, not articles.

For the "Author" and "Authors", only one of the field name can be used.

Not true. You can have both, but you probably shouldn't.

For the "Date:", it also takes in legacy time format of "2018-11-20T23:22.

date can be in pretty much any common format (dateutil handles conversion)

I think "Date:" and "Title:" should be marked as "mandatory."

title is mandatory. date is only mandatory for articles.

[egberts]

Probably should mention that the following fields cannot be left empty or you will get errors:

• Title: (mandatory)
• Date: Mandatory in article if ARTICLE_ORDER_BY = 'date' is used; Mandatory in page if PAGE_ORDER_BY = 'date'
• Modified: (optional)
• Author:/Authors: (optional, pick one, preferably Authors)

Delete those optional fields if they are an empty string.

[egberts]

I think "Date:" and "Title:" should be marked as "mandatory."

title is mandatory. date is only mandatory for articles.

Pelican is blowing up when I delete the 'Date:' out of a Page slug file, @avaris . Due to this pelicanconf.py setting:

 PAGE_ORDER_BY = 'date'

Probably should read as:

Date: Mandatory in article if ARTICLE_ORDER_BY = 'date' is used; Mandatory in page if PAGE_ORDER_BY = 'date'

[avaris]

Sure but that's your config, not something enforced by pelican. What I wrote is the requirements of pelican. If you put 'category' there then that becomes "mandatory".

PS: date is mandatory for articles regardless of what you have in settings. You can sort by something else but pelican will complain if you don't have date in an article.

[egberts]

Perhaps, some kind of note that "comma" symbols are not allowed in Title:?

I managed to crash it, but just not sure if this is the feature or a bug.

[justinmayer]

I can see how something like the table @marespiaut provided might be useful in the documentation. Do any @getpelican/reviewers agree?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your participation and understanding.

[justinmayer]

Based on the input in this thread, I submitted a pull request that improves Pelican's metadata field documentation. I am certain I did not fully capture all the information contained in the comments to this issue, so please feel free to comment on the above-linked pull request with any specific feedback.