Welcome to my new blog!¶

For those of you that don't know me or stumbled upon my new blog, let me introduce myself. I'm Jesus (Jesse) Caro, and I have been working in the data space for about 7 years as of 2023. When I started out of grad school, my primary language was R. I had a great blog written in R (powered by blogdown) that you can find here.

However, after a couple of years, I moved to a new role and picked up Python. I have been primarily programming in Python, and that blog was left neglected for a few years. It was primarily a mixture of laziness, and the lack of a solution equivalent to R-blogdown in Python. This is where Pelican and pelican-jupyter come to the rescue.

What is Pelican?¶

Pelican is a static site generator that allows users to leverage Python to create simple static sites. It has a variety of different features, and you can find more about them here. The requirements for my blog were only these:

• It should have a rich template base with decent-looking templates.
• Allow me to generate a static website using ipynb files.
• It should be fairly approachable over a span of a few months, and I shouldn't have to finagle and remember how to reuse it.

I would say Pelican knocks it out of the park on the latter two requirements, but the first one is definitely very lackluster. I found some decent templates, but you're going to have to do some digging if you want your blog to not look like it came straight out of the 00's.

How can you get started?¶

Getting started on Pelican is pretty easy. To generate this website I just had to do four things:

• Set up Pelican
• Grab a Template
• Install and set up pelican-jupyter
• Upload the output to a Static Host
  • (optional) If you want a domain name, set one up through GoDaddy

Set up Pelican¶

Setting up Pelican is a breeze! Before diving in, I suggest creating a virtual environment for your blog and printing out the requirements.txt file using pip freeze with explicit package versions (in case you migrate machines).

Navigate to a directory where you'll store your website data. For me, it's /Users/jcaro-work/VSCODE.

Create a virtual environment above that directory: /Users/jcaro-work/blog-venv by running python -m venv blog-env.

Activate the environment.

Run python -m pip install "pelican[markdown]"

Now, let's run and follow the prompts:

mkdir -p ~/projects/yoursite
cd ~/projects/yoursite
pelican-quickstart

Voila! You should now have a directory filled with config files, a content folder, and an output folder.

Grab a Template¶

A treasure trove of Pelican themes awaits in the repository-of-repositories. Currently, I'm using the "Hyde" theme (though it might change in the future). It's a modern and easy-to-use template that you might enjoy. Choose the one that best fits your style!

Theming is a breeze! In your pelicanconf.py file (created by pelican-quickstart), point to your theme by changing the parameter:

THEME = "/home/user/pelican-themes/theme-name"

Setting up Pelican-Jupyter¶

Setting up pelican-jupyter is also a piece of cake! Just use pip install pelican-jupyter. Ensure your environment meets the following requirements:

pelican>=4
notebook>=6
nbconvert>=5

Now, let's configure the way you want to use .ipynb files. Check out the [repo-readme] (https://github.com/danielfrg/pelican-jupyter) for various options. I've chosen Option 2 (metadata cell in notebook).

This requires you to add this code-chunk to pelicanconf.py:

MARKUP = ("md", "ipynb")

from pelican_jupyter import markup as nb_markup
PLUGINS = [nb_markup]
IPYNB_MARKUP_USE_FIRST_CELL = True

IGNORE_FILES = [".ipynb_checkpoints"]

Now, all that's left is to create a .ipynb file in blog/content, and you're good to go!

To do that, create an .ipynb file with the following metadata:

- title: Wow, Pelican is Cool!
- author: Bon Jon Bovine
- date: 2096-04-21
- category: snek
- tags: cool-stuff, awesome, tech, isn't-this-great?

Hit save, and run pelican -rl. You'll see an output like this:

--- AutoReload Mode: Monitoring `content`, `theme` and `settings` for changes. ---
Serving site at: http://127.0.0.1:8000 - Tap CTRL-C to stop

Now you should be able to see your website!

Upload the output to a Static Host¶

Apart from serving your website at http://127.0.0.1:8000, Pelican generates a static website at blog/output. You'll find tons of files there. You can upload this folder to services like Netlify or GitHub Pages.

The simplest way I've found is to use GitHub Pages. Define a directory in a parent folder (above the blog), copy the output there, and simply commit and push to the directory linked to GitHub Pages. This way, GitHub will refresh your static website without accessing any external websites.

Conclusion¶

Pelican proves to be a user friendly and quick static site generator, allowing bloggers to focus on content creation rather than complex setup. By following simple steps, users can set up a virtual environment and install Pelican with ease. Additionally, Pelican-Jupyter integration enhances data-driven stories by leveraging Jupyter notebooks to present insights simply.

While theme selection may be a bit frustrating, Pelican's adaptability ensures users can customize their websites to reflect their unique style and preferences. With the website generated, it can be hosted on platforms like Netlify or GitHub Pages, and the latter offers a simple and efficient way to refresh the static website with every commit.

#¶