Brian Gawalt's Blog (Pelican Edition)

These are the raw ingredients that power https://brian.gawalt.com/blog/.

Notes to self on how I set all this up.

Dev Workflow

Update content with a new Markdown post.

Test changes locally with

source ~/venv/pelican/bin/activate; \
cd ~/blog/; \
pelican --autoreload --listen

and then browse http://localhost:8000 to check it out.

Stand up the Jupyter backend with:

source ~/venv/jupyter/bin/activate; \
cd ~/blog/content/jupyter/; \
jupyter notebook --port 9999

Push to prod

Finally, create the final edition with:

$ pelican content -s publishconf.py
$ rsync -avc --delete output/ ../brian_gawalt_com/blog/

Then do the usual gawalt.com Git shuffle to deploy to the actual web server.

Dependencies

Pelican env:

$ python3 -m pip install "pelican[markdown]"
$ python3 -m pip install pelican-render-math

Jupyter env:

$ pip3 install jupyter
$ pip3 install matplotlib
$ pip3 install scikit-learn

Initial install

I am gonna try blogging by way of Pelican.

Commands executed so far:

The virtual environment for Pelican itself:

$ python3 -m venv ~/venv/pelican

This uses Python 3.10.6.

When that venv was active, I installed Pelican via:

$ python3 -m pip install "pelican[markdown]"
Collecting pelican[markdown]
  Downloading pelican-4.8.0-py3-none-any.whl (1.4 MB)
[...]

Then I created and navigated to this directory (~/blog) and ran the quickstart:

$ pelican-quickstart
Welcome to pelican-quickstart v4.8.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.]
> What will be the title of this web site? Brian Gawalt's Blog
> Who will be the author of this web site? Brian Gawalt
> What will be the default language of this web site? [en] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) https://brian.gawalt.com/blog
> Do you want to enable article pagination? (Y/n) n
> What is your time zone? [Europe/Rome] America/Los_Angeles
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) n
Done. Your new project is available at /home/bgawalt/blog

Official instructions

Viewing the generated files
The files generated by Pelican are static files, so you don’t actually need
anything special to view them. You can use your browser to open the generated
HTML files directly:

$ firefox output/index.html

Because the above method may have trouble locating your CSS and other linked
assets, running Pelican’s simple built-in web server will often provide a more
reliable previewing experience:

$ pelican --listen

Once the web server has been started, you can preview your site at:
http://localhost:8000/

Deployment
After you have generated your site, previewed it in your local development
environment, and are ready to deploy it to production, you might first
re-generate your site with any production-specific settings (e.g., analytics
feeds, etc.) that you may have defined:

$ pelican content -s publishconf.py

To base your publish configuration on top of your pelicanconf.py, you can import
your pelicanconf settings by including the following line in your
publishconf.py:

from pelicanconf import *
If you have generated a publishconf.py using pelican-quickstart, this line is
included by default.

The steps for deploying your site will depend on where it will be hosted. If you
have SSH access to a server running Nginx or Apache, you might use the rsync
tool to transmit your site files:

$ rsync -avc --delete output/ host.example.com:/var/www/your-site/

There are many other deployment options, some of which can be configured when
first setting up your site via the pelican-quickstart command. See the Tips page
for detail on publishing via GitHub Pages.