Building my static site with Pelican (part one)

I chose to use pelican for a few reasons:

• This site is hosted for free on GitHub and that means it needs to be statically generated.
• Pelican is written in python and I'm a python fanboy.
• Pelican is still in active development based on the merges, issues, and discussion on its repo in GitHub.
• Pelican has all the features I need plus I can supplement with other things like invoke (which I just learned about and am excited to try).

In the final structure, I will have one repo for the pelican install (thebouv-pelican.git) which will have settings, pelican files, raw assets like a post's markdown files and images. And one for the static site files (thebouv.github.io.git) because GitHub only serves from root or /docs. I feel this way is cleaner and allows the I will be automating publishing with invoke.

I am basing this process off of this tutorial but with some of my own ideas and organizational changes. Definitely fewer dependencies as I have no need for Jupyter Notebooks on this site, nor for now do I think I need typogrify or beautifulsoup as per that tutorial. I'll also be looking at the pelican quickstart and other pelican docs to make decisions as I go.

Setting Up

First I cleared all previous content out of my previous static site and leave only the README.md and CNAME files. The README will get updated during the project and CNAME is a text file required by GitHub to have thebouv.com as a custom domain. I could have set up a totally new repo or trashed this one and restarted, but with git I don't need to and I can always roll back one day or refer to the old site if I need.

Some git stuff

I create my empty repo for thebouv-pelican and set it up in GitHub as a remote:

mkdir thebouv-pelican
cd thebouv-pelican
git init
gh repo create

Notice the gh command. If you don't use the GitHub command line tool gh yet I do recommend it. It is pretty handy.

Pelican!

Now to set up my python environment and start getting Pelican set up. I'm doing this all with python 3.9.1 because it is stable and the most recent 3.9 release that pyenv has.

python -m venv .venv
source .venv/bin/activate
pip install "pelican[markdown]" invoke
pip freeze > requirements.txt

Now for the remainder of this post I'm going to no longer talk about being in a venv, activating, deactivating, etc. If I'm in a python project, I've got the venv activated. I assume the reader is managing this aspect.

I'm going to run the pelican_quickstart command line app and answer all the questions it poses. I'm filling out my site's details and pretty much accepting the defaults to things with defaults. Only thing is I'll be deleting the Makefile as I plan to use invoke instead to run the tasks in tasks.py.

I'm also manually creating a pages folder under the content folder generated by pelican_quickstart because I will want some stand-alone non-blog pages in the future like a resume.

pelican_quickstart
rm -f Makefile
mkdir content/pages

This leaves me with this structure below:

thebouv-pelican/
├── content
│   └── pages
├── output
├── pelicanconf.py       # Main settings file
├── publishconf.py       # Settings to use when ready to publish
└── requirements.txt     # saved earlier from pip freeze

Now that those exist and I want to start adding content, I want to do one thing real quick. I want to make my output directory actually be a git submodule of thebouv.github.io.git since the generated output will be in that repo.

git submodule add -f git@github.com:thebouv/thebouv.github.io.git output

Later I will automate committing and pushing both this repo and the generated content up to GitHub with invoke.

Theme

For now I plan to use a theme that is inside this repo called brutalistpelican but host just a fork of the theme for my own version. I'm doing this because I don't need the rest of his pelican set up (I have my own which this post is about) and only the theme itself. After I clone their repo I move the theme folder out and set it all up as its own repo. Then I can add the submodule like I wanted to do:

git submodule add -f git@github.com:thebouv/brutalist-theme.git theme/brutalist-theme

I've definitely made some changes to the theme that I'm not going to go into detail on. One of the main things I've done is get rid of any external javascript except Google Analytics. I also tweak page width to 60em max (non-brutalist but I wanted a slightly wider content area). I'll be making more changes over time and if they're significant, I'll write about them but likely most will be slight tweaks.

Any changes I make to the theme will need to be pushed up as well to its own repo but I can do it from the submodule itself which is handy and something I will be automating with invoke in part two of this post.

cd theme/brutal-theme
git add --all
git commit -m "some message about the changes I made"
git push

Let's fire this baby up!

This article, the one I'm writing and you're reading, is the first post in my blog. So the instructions below are so I can test this out locally and see it for the first time in all its simple glory:

invoke build

This statically generates all the content and uses the theme to style it. Then it puts all those static files in output which you'll recall is a submodule. Then I can go into that folder add all the output to git and push it up. And since it is set up to be hosted by GitHub once this output is pushed up, my site will appear here at https://thebouv.com

cd output
git add --all
git commit -m "auto-generated output from pelican"
git push

Next time

Okay, realize this is getting long and I have more to do but I've detailed everything that has gotten the site to this point. Well, besides the fact that I switched themes like 5 times but I didn't need to document that part. ;)

You can read part two if you want. :)