Fri 23 September 2022 | -- (permalink)

For a long time I was postponing to create a static website to note my personal projects and interesting stuff. Finally, I compared the different static website generators and I decided to use Pelican.

I was looking for a simple thing: Markdown syntax, no npm, go, etc. dependencies, Python would be OK. In short, I was looking for a hassle-free experience.

When you search for "Static Site Generators" top choices for people are usually:

I also use Jinja with flask so, it was an easy choice to pick Pelican and try it out.

Setup

Pretty easy, just install the library first:

pip install "pelican[markdown]"

Then, create a new project and provide some basic info:

pelican-quickstart

such as the project name, author, etc.

If you want to publish via GitHub Pages, say no to all previous options until the GitHub Pages comes up:

> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) N
> 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) y
> Is this your personal page (username.github.io)? (y/N) y

At this point, you will have a skeleton project with the following structure:

.
├── content
│   └── 
├── output
│   └── 
├── pelicanconf.py
└── publishconf.py

Create a Post

Pelican will automatically pick up any .md files under ./content (also directories) and will generate a static HTML file for each one of them. It is worthwhile to mention that .rst files are also supported.

You can also put any static image files under ./content/images and they will be copied to the ./output/images folder automatically when you run pelican content.

Generate Static Pages

To generate the static pages, just run:

pelican content

Run

To run the project locally with automatic reloads whenever you make a change in your content so you can see the changes in real-time:

pelican --autoreload --listen

Deploy

To deploy the project to GitHub Pages:

pelican content -o output/username.github.io -s .\pelicanconf.py

cd .\output\username.github.io\
git add .
git commit -m "New publish"
git push origin master

Themes

Pelican has a lot of themes available, but the catch is they are not in the package, you have to pull another pelican-themes repository and use the one you want.

I recommend checking the live demos of the themes to see which one you like the most from here: http://www.pelicanthemes.com/

Then provide the directory of your theme in the pelicanconf.py file:

THEME = r'.\pelican-themes\pelican-bootstrap3'

Conclusion

That's all, after you complete the initial setup & boilerplate, you can create a .md post and generate & deploy in one script call (above in Deploy section).