Homepage of Stuart Maynes, Software Engineer

Using a CMS with Pelican

When I first started using Pelican1 I wrote my articles using VS Code. This worked fine, but recently I have started using Obsidian2 to take notes and I now want to use it for all my writing.

Markdown3 editors, such as Obsidian, can handle the library of files in several ways. The file library can be fixed, configurable or nonexistent. For apps that have a configurable library one option is to set the library location to the Pelican content directory. For apps with a fixed library location or for where you have a reason to use a different location, Pelican can be configured to use a custom directory.

A markdown editor with a library can then be used as a type of CMS. Depending upon the markdown editor you use advantages can vary. But, what I like about using Obsidian is the fact that it makes it easy for me to reference my existing notes. This ease of reference greatly speeds up the writing process. The ability to link information together in Obsidian is also a great way to see novel ideas for content.

Library location

Pelican by default will look in a folder called ‘content’ but this can be changed by setting the PATH variable in your pelicanconf.py file.

PATH = /location/to/your/markdown/files/

The downside of using a directory outside the project root is content and project files will no longer be version-controlled as part of the same repository. If you have another way of backing up your files, this may not be a concern, but it is worth considering.

Reducing metadata

Pelican by default tries to get as much of the metadata information as it can from the file system. This means that there are only two necessary bits of metadata – title and date.

Categories

Subfolders can be used to categorise articles in Pelican. The folder structure shown below would result in an article ‘The Pythonic Way’ categorised as ‘Python’.

Content
- Python
-- The Pythonic Way.md

There are no explicit settings needed for this to work. It’s out of the box behaviour4. The setting that controls this is:

USE_FOLDER_AS_CATEGORY = True

If a file is situated at the root of the content directory then the article will be categorised as ‘misc’. The default category can be set with:

DEFAULT_CATEGORY = 'Thoughts'

Title

The title can be set to be taken from the name of the file with:

FILENAME_METADATA = r'(?P<title>.*)'

A file called ‘The Pythonic Way.md’ will be given the title ‘The Pythonic Way’; removing the need to explicitly set the title in the metadata.

Date

The date for the article can be extracted from the file system timestamp with:

DEFAULT_DATE = 'fs'

The downside of using fs is whenever the file is saved the timestamp is updated. This means the order of the posts could be affected. To overcome this, FILENAME_METADATA can be adjusted to parse a date from the file name.

Date and Title

FILENAME_METADATA = r'(?P<date>\d{4}-\d{2}-\d{2})\s(?P<title>.*)'

As an example, an article titled ‘The Pythonic Way’ written on 01 February 2021 would be saved as 2021-02-01 The Pythonic Way.md.

Omitting the date from the filename would result in the file not being published unless there was a file-level override.

File-level overrides

Any metadata added to the top of the file will take precedent over the data extracted using the settings present in the pelicanconf.py file.

Title: Have a great new year
Slug: new-year
Date: 2020-01-01
Category: Festivities

With the above set in a file saved as 2019-12-31 New Year.md the result would be an article titled ‘Have a great new year’, published on 1st Jan 2020, categorised as ‘Festivities’ with a URL of ‘new-year’.

Conclusion

Hopefully you found this post useful and even if you don’t change your markdown editor, you may have learnt a few settings that you can use to reduce the amount of metadata in your files.

I haven’t been able to go completely metadata free as I use draft posts and I find that the automatic summary is insufficient. My intention was never to remove metadata but to setup Pelican in a way that made sense to me.


  1. Pelican is a static site generator, written in Python

  2. Obsidian a knowledge base that works with local folders of plain text Markdown files. 

  3. Markdown is a small markup language for creating formatted text plain-text files. 

  4. Pelican uses folders as categories by default.