One of the challenges (amongst many) of publishing posts on this blog is the number of manual steps I have to take. I'm not using a content management system or one of the many static site generators such as Hugo, Jekyll, or Pelican. Instead, I write each post in markdown and then use pandoc to generate the HTML file using some slightly modified templates, header and footer files, and a custom css file. It's not pretty or easy but so far, it works. I may write a future post explaining how it all comes together if I can find the wherewithal.

The process is cumbersome enough that I've been evaluating options to make publishing posts to a static site easier. One dark horse candidate that I came across is called ikiwiki which is a static site generator, written in Perl, that you can use to publish wikis or blogs. It has the right combination of functionality and simplicity that I am looking for so I've been giving it a spin. In this post, I'll document how to install and use it on FreeBSD.

To install it, run the following commands:

$ sudo pkg update
$ sudo pkg upgrade
$ sudo pkg install nginx fcgiwrap ikiwiki

Enable NGINX and fcgiwrap by adding the following lines in /etc/rc.conf:

nginx_enable="YES"
fcgiwrap_enable="YES"
fcgiwrap_user="www"
fcgiwrap_socket_owner="www"
fcgiwrap_socket_group="www"

Now you can create your ikiwiki blog or wiki by running one of the following two commands:

$ ikiwiki --setup /usr/local/etc/ikiwiki/auto-blog.setup # to create a blog
$ ikiwiki --setup /usr/local/etc/ikiwiki/auto.setup      # to create a wiki

Follow the prompts and answer the questions that follow. Upon completion, you may see some errors or warnings. I found that I had to edit the setup file (nameofblog.setup) located in the home folder to set the following:

allow_symlinks_before_scrdir: 1

and then run

$ ikiwiki --setup nameofblog.setup

Now we can configure NGINX:

$ cd /usr/local/etc/nginx/
$ cp nginx.conf nginx.conf.bak
$ sudo vim nginx.conf

Update the root and server declarations in /usr/local/etc/nginx.conf according to my prior post on configuring NGINX on FreeBSD where server_name is your domain and where root is /home/username/public_html/nameofblog.

Restart NGINX:

$ sudo service nginx restart

and your new blog should be ready at the URL of your domain. You can also follow my instructions on how to enable HTTPS which is highly recommended.

To remove the ability to add new posts from the home page, remove rootpage="posts" from /home/username/nameofblog/index.mdwn. After that, you can begin your journey to further tweak, refine and customize the look and feel of the site. There are too many options to get into here but the ikiwiki site has a lot more information on how to install plugins or customize the templates upon which the pages are based. I would recommend reading through the documentation to better understand all of the features and capabilities.

As for me, I haven't decided yet if I am going to convert over to ikiwiki or some other static site generator. I don't blog often enough to justify the conversion, but perhaps I don't blog that often because of all of the friction involved.

Stay tuned.