Fine Tuning Pelican: Publishing, Drafts, and Document Status Defaults

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 creating content for the website, it is often desired to group articles together that are in various stages of readiness for publication. Prior to publication, many content authors want to see how their content will actually look by preparing a draft of the content that only they can see. This article discusses settings that address both of those concerns.

What Does the Document Status do?¶

As part of the standard Pelican feature set, an article or page may have a status of hidden, draft or published. If the status is hidden, then it is ignored by Pelican, and no further action is taken. If the status is draft, then it is published under the drafts directory and not registered with any of the navigation maps. Finally, if the status is published, then it is published using the standard Pelican article and page mapping, and it is registered with the standard navigation maps. While there isn’t much information on the status metadata tag, it is included in the main pelican documentation on File Metadata.

Without any relevant DEFAULT_METADATA settings being changed (more on that in a minute), the default value for status is published. As such, as long as the article is in the right place to be picked up, it will be published as part of the website. If a draft version of the article is desired, then the status metadata must be set to draft as shown in this example markdown article:

---
Title: Some Markdown Article
Category: Quality
Status: draft
---

My markdown article.

Unlike the normal publishing process, the rendered version of this file will be placed in the website’s /drafts directory, most likely with a name such as some-markdown-article.html. While it is obvious that the page was created by looking at the output from the publishing of the website, this page will not appear on any summaries or searches on the website. This can all be changed by changing the status metadata to publish and re-publishing the website.

Setting a Document Status Default¶

This information is largely taken from Pelican’s Publishing Drafts section. As is mentioned in that section, to change the metadata default for articles and pages from having a default status of published to a default of draft, the following text much appear in the pelicanconf.py file:

DEFAULT_METADATA = {
    'status': 'draft',
}

While the Publishing Drafts article does mention that to publish articles and pages, their metadata must now include a Status: published metadata line, I feel it does not stress this enough. When writing articles from that point forward, it may be easy to remember to add that metadata tag to each article. However, to ensure that any previously published page or article is still published, each previous article and page must be revisited and that metadata line must be added to those article’s metadata section.

What Was Accomplished¶

When authoring content, it is often desired to group articles in a series together, often in different states of readiness. This article started by looking at the document status and how it works for Pelican, and then moving on to how to set a new default for a Pelican-based website. Finally, a note was added to Pelican’s own documentation on document status to help any readers avoid “losing” any published articles if the default document status is changed.

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