The problem

The default workflow for pelican is to have a single site online and to use a local webserver to test things. For different purposes a list of directories can be defined. E.g. directories where files are located for uploading or directories where articles are located.

For my purposes this setup is impractical for the following reasons.

• I want to organize my content (article, files for download, other files e.g. image source files) in one subdirectory per project.

  • This means that there will be files and directories which pelican should ignore.

• I want to start writing draft versions of articles but not publish them.

  • Pelican offers a "draft" but this simply hides the article from the index. One cannot see the summary of the article if it is not listed in the index.

The solution

• I keep the source files in a separate directory. In this directory all files can be organized in subdirectories as needed.

• For each target I create a list of files filelist.*BLOGNAME*.txt.

  • The target "everything" includes the whole content directory.

    • It is only served locally and can be used to quickly generate new content without caring for the filelist.

  • The target "staging" includes the articles and files which should be published online.

    • This target is uploaded to a private directory on the webserver. Here, I can test if everything works and all dependencies are included and correctly linked.

  • The target "publish" includes the files actually needed for the public site.

• A script crawls the source for filelist-files and creates the corresponding links in the target directory.

• Another script compiles each blog and starts a webserver locally for each.

• Another script is used to compile and upload "staging" and "publish".

This workflow is virtually identical to having the content directly inside the pelican directory when creating new content and serving it locally in "everything". But all files belonging to an entry can be kept in the same subdirectory. In order to publish the filenames must be listed, which is extra work. This step is an additional safeguard against publishing the wrong files. A quick test with the "staging" target reveals if all files are correctly included and then the filelist can be copy-pasted to the "publish" target and uploaded to the main site.

When regenerating the blog for local serving my command order is make clean, make html, make regenerate &, make serve. Here, make regenerate is very useful to quickly update the site locally each time a source file is changed. But when a file contains an error make regenerate crashes. This means that this command must be restarted each time - either manually in the console or better automatically using a script. I therefore wrote a script which executes these commands for all targets, starts local servers on different ports and restarts make regenerate automatically. Another skript handles uploading.

For file linking and regenerating the blog automatically and starting the webservers I simply execute the script

./serve_locally.sh`

this handles all 3 versions and in the case of everything all new files are automatically integrated even after the script is started.

When everything is ok, I start

./publish_online.sh

which regenerates the blogs and uploads them using rsync over a ssh-connection.

This makes writing new content very efficient. And the management tasks only take a minimum of time. The scripts are tested on OSX and Linux.

git

Since the blog articles are all text files, a source code management tool such as git is pretty well suited.

In my setup the master repository includes the scripts, my theme and plugins and two submodules:

1. the pelican-plugins from GitHub,
2. the content including the configuration files.

I have a bare upstream repository on a shared folder for data exchange between different machines.