Using Pelican





To run Pelican using virtualenvs

Run

virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
source bin/activate

Then go to the Pelican folder, and run make html (or see below)

Generating website using make

To generate the website:

make html

To automatically generate the website (i.e. monitoring the folder)

make regenerate

Metadata

Apparently title is the only metadata that is compulsory. NB: But you need to first include DEFAULT_DATE = 'fs' in the configuration file.

Categories

  • Every post will have one category. No more, no less.
  • If not specified, category is set to "misc"
  • The name of the category can be more than one word

Tags:

  • Every post can have any number (incluing 0) of tags
  • Each tag is to be separated by a comma
  • Do NOT have a trailing comma (it screws the tag presentation up for certain themes)
  • If not specified, tag is not displayed.

Automatic generation of date and slug

It is possible to generate metadata from the filename (except for the "title" metadata)

e.g. (In the configuration)

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

This allows the date in the filename to overide the "mtime" of the file itself.

If the file name is not in the format of YYYY-mm-dd-SLUG, then the slug is generated from the title as per default, and the date is based on "mtime" of the file.

Linking to internal page

Normally in markdown we link this way:

This is a link to [google.com](http://www.google.com)

→ This is a link to google.com

To link to another page on the site, we need to slightly modify the standard markdown code.

Use as URL:

{filename}/relative/path

Therefore, we say

This is a link to the [About]({filename}/pages/About.md) page.

→ This is a link to the About page.

NB:

  • Path is relative to the /content/ folder.
  • Spaces: If there are spaces in the filename, apparently Pelican is smart enough to recognise it. No quotation required (actually I think quotation breaks it.).
  • Capitalisation - It matters. "test.md" and "Test.md" are not interchangeable.

Embedding images

Same markdown syntax, with similar modification as for linking, i.e.

![Alt text]({filename}/extras/images/testimage.jpg)

For example,

![Test image]({filename}/extras/images/Test123.png)

Gives this result:

Test image

In contrast,

[Test image]({filename}/extras/images/Test123.png)

i.e. No leading !, gives this instead:

Test image

Limitations:

  • Any image has to be in a static folder
  • There can be no space in the filename. This is due to a bug in the markdown parser. If RST is used instead, space in the filename is allowed for images.

NB: Unlike posts and links, image cannot be displayed if there is space(s) in the file name (but they can still be linked).

Colorised syntax highlighting for code blocks

Use :::[identifier] at the start of the block quote, to get this:

echo "Hello world!"

Identifier can be, e.g. bash, ruby, python, etc.

Static folders

By default, only the "images" folder under content will be copied.

If you want another folder, say "files" folder to be copied to, add this to the configuration file:

STATIC_PATHS = ['images', 'files']

ALL of the static folders and their content will be copied, regardless if these files are referred to or not.

On the other hand, if the file is not in one of the static folders, it will not be copied. (even if it is in the root (i.e. /content/) folder.

In other words, unless a file is processed by Pelican (e.g. a markdown file) or in the static folder specified, it will not appear in the output website.