Logo DCEtech

How to use Pelican: Markdown files, theme selection and customization.




In the previous post you have the introduction about how to start with pelican, and in this one I´m going to share more info about how to use pelican.


Markdown Files to generate articles:


One of the main reasons I choose Pelican, I can use a simple files to generate my content with a light and simple syntax. How can I make an article in pelican? Simple, create a markdown file that name ends in .md or mk in the content directory and use this structure in your md file:


Title:
Date:
Category:
Tags:
Author:
Content goes here..


Theme Selection:


One of the most powerful features of Pelican it´s that you can choose different themes, this themes are opensource that the pelican community provides, you can find different themes in this link Pelican themes. If you want to change the theme that pelican have by default, here you have some steps:


1º Create a directory named themes in your pelican project and clone the repository that the theme you choose:


mkdir themes
cd themes
git clone https://github.com/username/repository-name.git


2º Configure pelican by the new theme in file pelicanconf.py:


THEME = 'themes/repository-name'


3º Generate you site with the new theme:


pelican content
pelican --listen


Customize our own theme and what is Jinja2?


img.png


Up to this point it hasn´t been necessary nothing to code in HTML or CSS. However, if you want to customize your own theme, you´ll need to have some basic knowledge of HTML, CSS and jinja2. I assume you´re familiar with HTML and CSS, but you might not know much about Jinja2. Let me explain: Jinja2 is an extensible template engine used in Python that allows developers to create HTML templates that can be reused and filled with dynamic content. In Pelican, Jinja2 is specifically used to inject content into templates and render them into HTML files during Pelican´s build process. What does this mean? It means that Pelican uses this technology to manage the HTML and the markdown files to produce the final HTML that generates the website. If you are interested to learn more about Jinja2 visit their website Jinja.


Ok, with this brief introduction about Jinja2 let´s continue to customize our own theme. To create and customize you own theme it´s easy if you have the basic structure to work in it, in the Pelican website suggest to use the simple theme to create our own theme, this is our basic structure. Here are some steps:


1º Install pelican themes:


pip install pelican themes


2º Go to Pelican project directory venv/lib/site-packages/pelican/themes/simple and copy the simple theme in our themes project directory that we created before. I recommend to rename the directory for something like mytheme or similar to this.


3º Configure the pelicanconf.py with the new renamed theme:


THEME = 'themes/mytheme'


4º Generate the site, to view the changes:


pelican content
pelican --listen


If you followed the steps correctly you might view also like this:


img.png


Ok, this is really simple now it´s your turn to play with HTML and CSS to customize and create a nice website, just a few pieces of advices be careful with the project directory, as it´s very sensitive for any change, use the Jinja2 it´s really useful and have a happy coding.