Hello, world.

Well it only seems fitting that the first post I write for this iteration of the site would be a description of how I made it. As I go back and add content from the old site(s) to this one I’m going to manually update the timestamp to the original posting time. So things may be older on the site - but this is the first post. This site is a static site generated with Pelican and hosted on Netlify. I chose Pelican because I wanted a static site generator, and I wanted it to be associated with Python if possible, and I wanted to use Markdown to write the actual posts and files. I don’t require anything like Django right now … maybe later.

Assumptions: You have a GitHub account, and GitHub desktop is installed and configured. Anaconda is installed and configured. You’ve got a Netlify account.

Setup

1. I like Anaconda, so I defined a new environment there. I double checked that python was at least version 3.8, and installed pelican and markdown, along with whatever dependencies those brought about.

2. Since I prefer to use GitHub desktop I fired that up and clicked on File > New Repository. I gave my new repo a name and description and pointed the local path to the repos folder to let the application create the subfolder based on the name of the repository. I created the README so I could populate it later. Since I was creating my own Git ignore file later I did not choose one here and I since this is a Pelican website I used the GNU AGPLv3 license to respect the license of the original project.

3. Now I opened the project folder and create a file called .gitignore. Into .gitignore I added the default Python exclusions from gitignore.io, and at the end of the file I added

   # Pelican output directory
       output/

   After committing that to the repo the standard Python bits, as well as the output directory of the site itself, are not going to be pushed to GitHub. That’s fine since Netlify will be rebuilding the output directory locally every time I commit a new change to the repo.

4. From inside the project folder, I setup the pelican structure with the command pelican-quickstart. This launched a configuration wizard. I accepted the defaults except for:

   • “What will be the title of this web site?”
     • This is written to the pelicanconf.py file as the SITENAME
   • “Who will be the author of this web site?”
     • Written to pelicanconf.py as AUTHOR
   • “Do you want to specify a URL prefix?”
     • Set this to N. When I specified Y then the URL was used instead of relative paths for images which made local development pretty much impossible.
   • Get the timezone for the site from Wikipedia, and enter it when prompted

Customise Pelican and Prepare It For Netlify

1. I wanted to have a bit of a theme on the site from the beginning, so I hunted around on pelicanthemes.com and settled on the nest theme. After messing about with it a bit I discovered that it needed to be changed to work with the version of Pelican I was using. So I forked the original theme and applied the changes to the fork.

   • To do the changes I edited base.html on the theme and changed four instances of ‘|format(’ to be ‘.format(slug=’, so that CATEGORY_FEED_ATOM|format(category.slug) becomes ‘CATEGORY_FEED_ATOM.format(slug=category.slug)’.

   After that, I created a /theme folder in the project folder, and downloaded the theme to it.

2. In the project folder under /content, I added an images folder and a file there for the logo of the site. I scaled it down to 25x25. I also added an image for the background of the header.

3. To pelicanconf.py I added the default configuration information for the theme. Among other customisations for various strings I pointed the site logo to ‘/images/logo.png’, including the path, and homepage header image specified as the filename only, ‘header-scaled.jpg’.

4. That should be the base of the site. I committed those changes to the repo and test built the site locally with

   pelican content -d -s publishconf.py -t theme --autoreload
   pelican --listen

   … which you can now combine on Windows as

   pelican content -d -s publishconf.py -t theme --autoreload --listen

   Alternatively you can skip the second command for –listen and use a local server like Live Server in vscode to actually view the site.

   The -d flag causes pelican to delete the content directory before rebuilding the site. The --autoreload flag tells pelican to keep watch on the content folders and rebuild the site automatically when content is added, edited, or removed. As expected, that gave me a functioning site on http://localhost:8000 with the logo and background images I specified.

   1. Special usage note: until the site is building reliably, just use

   pelican content -d -s publishconf.py -t theme

   …so you can see the console errors in the build process.

5. Now that the shell is working, I created a requirements.txt file of the working environment, both as a checkpoint myself and also so Netlify will be able to duplicate it, with the command pip freeze > requirements.txt.

6. When I tested this originally, Netlify was deploying the site with Python 2.7 which was not at all working. So to specify the version of Python I was using locally, 3.8, per the docs I created a runtime.txt file in the root of the project, and added 3.8 to that file.

7. After committing those changes to the repo, it’s ready to go. So I published it to GitHub with the desktop app. I left the repo set to private at this point.

Deploy the site to Netlify

All that remains is to deploy the site with Netlify.

1. I logged in to Netlify and selected Sites > Add New Site > Import an existing project.
2. On the next page, I clicked GitHub.
   • The first time I did this I needed to connect my Netlify account to my GitHub account by following the prompts.
3. Once GitHub and Netlify were connected, I did a search on my repos to find the one for the website, and selected it.
4. On the next page:
   • on branch to deploy I selected main.
   • The base directory I left blank.
   • The build command is pelican content -s publishconf.py -t theme
   • The publish directory is output.
5. That’s it. I clicked on Deploy Site and awaited …

… the shell of my site was deployed to Netlify. Volia.

After that all that remained was to re-direct my domain to point here, and configure the Let’s Encrypt certificate to enable HTTPS. This is available under the Netlify Site settings for the new site. Following the directions on the Netlify pages this change took me all of 4 minutes of editing on my DNS server, and the deployment of the SSL certificate was a couple of clicks and otherwise automatically done in a few minutes.

And that’s it. After several years of stalling I have completed a reasonable starting point for a new static site version of the website and deployed it. Took me a couple of hours to figure it all out, and maybe 20 minutes start to finish for the final production version. Hope this helps.

Thanks!

• Raz, for general direction here and here
• Frank Corso for the general directions here
• Miraj Patel for the pointers to hack the theme so it would work with Pelican 4 here