First step is to download and install Pelican. I do it with virtualenv but you can check out other alternatives at Pelican's website². I open a terminal, navigate to the directory where I keep my virtual environments, and then execute the following commands:

virtualenv pelican           # creates the virtual environment
source pelican/bin/activate  # activates the virtual environment
pip install pelican          # get and install Pelican

If you don't have virtualenv already installed, probably you can find it on your GNU/Linux distribution packages. If your system does not provide the package check out Virtualenv's official docs³.

The virtual environment stays active in this terminal session until you run deactivate. Don't do that yet, you still need it for the upcoming steps.

Once you have Pelican installed you should follow the quickstart steps to create the web site:

mkdir -p /local/path/to/your/website/project/folder   # create a folder for your web project
cd /local/path/to/your/website/project/folder         # mone inside the folder
pelican-quickstart                                    # execute quickstart

As part of the quickstart process, Pelican will prompt you with a set of questions to configure your website project. The answers will vary depending on your needs, but here are the prompts with sample responses to guide you:

> Where do you want to create your new web site? [.] 
> What will be the title of this web site? My Web Site
> Who will be the author of this web site? myself
> What will be the default language of this web site? [en] 
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) https://mysite.com
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Rome] 
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost]
> What is the port of your SSH server? [22] 
> What is your username on that server? [root] user
> Where do you want to put your web site on that server? [/var/www] 
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) N

At this point, you can execute deactivate on the terminal to leave the virtual environment, we have a few things to take care of before we need it again.

To accomplish our goal we will need the org_reader plugin⁴. Let's get Pelican's plugins. The quickest way to get the plugins is by cloning the GitHub repo⁵ and put them inside a folder. Navigate to the folder where you want to store the plugins and clone the repo:

cd /path/to/folder/where/plugins/will/be/stored
git clone --recursive https://github.com/getpelican/pelican-plugins

Now open the file pelicanconf.py and add the following right at the beginning:

import os # this line shold be already inside the file

PLUGIN_PATHS = ["/path/to/pelican/plugins/folder"]
PLUGINS = ["org_reader"]

If you have an Emacs installation in a non-standard location, add the following line:

ORG_READER_EMACS_LOCATION = "/path/to/emacs/bin/emacs"

Let's write a first post in order to see a basic template you can reuse when writing new posts.

There are a lot of properties (metadata in Pelican's jargon) which you can use to set up a post. Here I'm only including the ones I consider most common and/or important. You can check out Pelican's and org_reader's docs (see footnotes) to get the full list.

Inside the content/ folder of your Pelican website create a file hello-world.org with the following content:

#+TITLE: Hello World!
#+DATE: 2024-05-24
#+AUTHOR: admin
#+LANGUAGE: en
#+CATEGORY: Programming
#+PROPERTY: LANGUAGE en
#+PROPERTY: SLUG hello-world
#+PROPERTY: SUMMARY This is the post summary
#+PROPERTY: SUMMARY+ and it can have multiple lines
#+PROPERTY: TAGS programming, clang

Next we will see Hello World source code in C.
#+BEGIN_SRC c
  #include <stdio.h>
  int main(void)
  {
          printf("Hello World!");
          return 0;
  }
#+END_SRC


#+BEGIN_EXPORT html
<hr>
<center><small>
And this is a HTML block.
<p>
<a href="https://creativecommons.org/licenses/by-nd/4.0/">Creative Commons Attribution-NoDerivs 4.0 International (CC BY-ND 4.0)</a>
</p></small>
</center>
<hr>
#+END_EXPORT

Let's see the meaning of all these properties:

• #+TITLE: Hello World! this is the only mandatory property.
• #+DATE: 2024-05-24 the date of the document. It could be an iso format date or an Org Mode timestamp.
• #+AUTHOR: admin author name
• #+LANGUAGE: en document language for Org Mode
• #+CATEGORY: Programación post category
• #+PROPERTY: LANGUAGE es document language for Pelican
• #+PROPERTY: SLUG hello-world if you don't use this property, Pelican will use file_name.org
• #+PROPERTY: SUMMARY post summary
• #+PROPERTY: TAGS programming, clang all the tags you want to use

Apart from the properties shown in the example, there is one I find essential: #+PROPERTY: STATUS. This property can have the following values:

1. published: this is the default status
2. draft: post will be stored inside the drafts/ folder, inside the website, and it will not be linked anywhere.
3. hidden: post is not linked anywhere, so you should know the exact URL to get to it.

Therefore, if you want to have a hidden post, you should add this property:

#+PROPERTY: STATUS hidden

The moment of truth has arrived, time to see the results of all the work you have done, check that everything works, and find out how to generate and publish your new website

From inside your site's root folder follow these steps:

1. Activate the virtual environment

      source /path/to/pelican/virtualenv/bin/activate
   

2. Start the site preview in your local system by running:

      make devserver
   

   If you look closely, the previous command will return, among other things, the following:

      Serving site at: http://127.0.0.1:8000 - Tap CTRL-C to stop
   

   Copy & paste the url http://127.0.0.1:8000 in your favourite web browser in order to see your website. The devserver mode automatically rebuilds the website whenever changes are saved in the *.org file, allowing you to view the updates instantly by refreshing the browser.

3. You can quit the devserver mode by pressing the keys CTRL-C. Now you can publish your website by running:

      make rsync_upload
   

   Executing this command will rebuild the whole site and deploy it to the destination configured during the quickstart setup. If this doesn't work or isn't available, open the Makefile located in the root directory of your website, where you will find all the possible deployment options (ssh_upload, sftp_upload,…).

This howto has introduced the basics of creating a website using Pelican and managing content with Emacs and Org Mode. The next step is to explore Pelican in more depth to customize your site. Consult the Pelican documentation, choose a theme⁷ you like, or make a custom one.

I want to thank BxCx from #emacs-es channel on Libera.chat⁸ because the idea for this howto originated when he started talking about creating a static site with Emacs, and he asked me about how I built my site.

I want to thank Anten Linevich because without his post I wouldn't have figured out how to enable syntax highlighting.

This howto is Copyright © 2024-2025 Lucio F. Albenga and is released under the terms of the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).

Source code of pelican-html.el file is Copyright © 2017-2024 Anten Linevich Creative Commons Attribution 4.0 International (CC BY 4.0)