Step By Step Guide To Setup a Web Site Using Pelican and GitPages
In this article, we’ll see how to use a couple of cool things together to create and host a simple website.
Why this choice?
If you need to set up a simple website, like a personal site, brochureware, a landing page or something similar, there are easy solutions to consider, maybe less famous respect specific services or standard applications, but bringing the same results.
In tech — but is something valid everywhere — there is no one fits solution, but the best choice is derived as a tradeoff from the context, the needs, the expected outcome and the available resources — time, skills, money.
I had to make this choice for a project I’m currently involved — publish a site to make available articles about Artifical Intelligence and Machine Learning actually on GitHub as markdown files — so it’s personal! :)
The first idea was to use Wordpress and adding a theme for front-end customization. It seemed a fast solution at first but, after some tests, it turns out that the porting from markdown files to Wordpress articles was a bit long and that it was necessary to prepare local and production environments, the latter with a range of solutions from setup everything manually on a generic cloud provider to use a Wordpress dedicated hosting solution, like WPEngine.
Too many complications respect the final objective, at least for this first phase.
Moreover, it will be necessary to continue to manage new articles from GitHub and then porting to Wordpress, something could need automation and relative effort.
So, why not using directly the markdown files, convert in HTML format and publishing them as static files?
But also, it would be nice to have a basic structure without making it from scratch, at least static content such as FAQs, contacts and posts, allowing to model the website in a blog-like style.
Finally, some fast graphical customization as a starting point to work from.
And here where Pelican comes into play.
Pelican
Pelican is a static site generator, made in Python
From its site:
Maintained by Justin Mayer (@jmayer), Pelican is a static site generator that requires no database or server-side logic.
Some of the features include:
- Write content in reStructuredText or Markdown markup
- Completely static output is easy to host anywhere
- Themes that can be customized via Jinja templates
- Publish content in multiple languages
- Atom/RSS feeds
- Code syntax highlighting
- Import from WordPress, RSS feeds, and other services
- Modular plugin system and corresponding plugin repository
… and many other features.
Seems it has everything needed for this project, so let’s see it in action!
Installation
The simplest way is to use pip and Markdown support, so
pip install pelican[Markdown]Then just run the setup
pelican-quickstartanswer some questions about your site
yourproject/
├── content
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py # Main settings file
└── publishconf.py # Settings to use when ready to publishand you’ll end with this basic folders structure
The content is where to put the input files, but we’ll see this in a moment.
Pelican handles two types of content:
- Pages: the static parts of the site
- Articles: basically, kind of blogs post
Adding content
Let’s add a page first
This is the home page, so let’s call it home.md and put it inside content/pages folder.
To instruct Pelican during generation, it’s important to add some metadata such as Title, Date and Author
Title: Welcome to Pelican!
Date: 2019-10-20 09:20
Author: Antonello## Welcome to PelicanHello!
Very easy…let’s add now an article.
Let’s create a subfolder “articles” and let’s write inside it a file named pelican_article.md, something like this:
Title: An article about Pelican
Date: 2019-10-20 11:20
Author: Antonello
Tags: pelican, tutorial## Using Pelican to generate static filesIn this post we'll see how to use Pelican to generate a static file
Great, now is generation time. To do so we have two options: doing on-demand or let this triggered every time our files are updated.
Let’s starting manually and to do so just launch command pelican content
This is what happening…
At the bottom, the command results, telling us the processed items
On the left, you can see in the output folder, all the generated files, based on author, articles, pages, tag and a bunch of static pages to use as entry points.
Time to see our site live! To do so, just let’s launch make serve command and point browser to localhost:8000
This is the article, with the metadata wrote on file. Notice the created menu, containing the page and the articles categories, based on the folder name.
Let’s say we want to create a specific category, for instance ‘Python’. To do so, let’s edit the article in this way, adding category metadata.
But first, let’s use the second way to generate the content, launching make devserver so you’ll see this live after updated the file and (hard) reloaded the page on the browser.
Title: An article about Pelican
Date: 2019-10-20 11:20
Author: Antonello
Tags: pelican, tutorial
Category: Python## Using Pelican to generate static filesIn this post we'll see how to use Pelican to generate a static file
Now the page contains that category
Notice the old HTML files remained in the output folder, meaning the generation is additive and will not remove older files unless you delete entirely the output folder before recreating it, something to do before publishing the site.
Changing look and feel
So far, so good, but what if I want to change how it looks? It’s possible to use themes and then customize them. There are a lot of them available that can be downloaded (and forked for changes) from public repos.
To have a preview, this is the site to look at: http://www.pelicanthemes.com/
Switching to another theme is just one row configuration, in the pelicanconf.py file (let’s suppose to have cloned Flex theme in a parent directory)
THEME = ‘../pelican-themes/Flex’
Voilà, a completely different look and feel — notice menu is not present, so be careful, because switching to a particular theme can have impacts on the navigational structure of the site.
This is just a very basic approach, but it’s possible to add Google Analytics, configure a specific site url, adding comments with Disqus integration and other interesting features.
Take a look at the official documentation here: https://docs.getpelican.com/en/stable/
Publishing the site
Ok, now the final part: publication on GitPages. There are several approaches here, but the simplest one is to create a Git repository inside the output folder and then push to GitHub, enabling then GitPages.
Let’s see it, but before we just reuse the default embedded theme for simplicity (commenting the THEME configuration we added before) and set RELATIVE_URLS = True on pelicanconf.py, otherwise css will be not found when served form GitHub.
After the push, go to Settings,
enable GitHub Pages for the repo
and the site is live!
Conclusion
KISS approach is something I tend to use whatever possible and this solution seems to me a great tradeoff between simplicity and flexibility, so I hope this guide will be helpful to give it a try if interested.
See ya
