The simple web

Maybe not so simple :-(

A couple of months ago I wrote this workshop in the hope that I could teach package management, git and how to build and host your own static website all at once in a few hours.

The first iteration went well but the second time I've done it not so much, some code rot and a couple of the participants couldn't get their website up and running (so sorry for that folks!).

Code rot is such an interesting problem to me, a relique of human interaction patterns. Knowledge gets lost and corrupt even if we don't have Alexandria disasters anymore.

Anyway, I'm writing this blog post to address the problems we encountered on the workshop. It consists of two parts: the first one is how to fix the issue you encounter (if you encounter it) and how to upload your website. The second part is offering an alternative to Jekyll and Ruby's convoluted system, by using HUGO which is a newer alternative that's very very similar to Jekyll but newer and less prone to code rot. It also offers slicker themes for your website.

Getting things working

If you run into issues saying it's not possible to install the gems there are two different solutions you can try.

Installing ruby and jekyll with your local package manager

If you're on an OSX machine you can try to work around this problem by using brew.

Install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install Ruby:

brew install ruby

And Jekyll:

gem install jekyll bundler

You might also need webrick:

gem install webrick

If you're using Linux follow the same steps using your package manager + the gem step.

If you're on Windows, try to do the same but using Chocolatey.

Changing environmental path

you might need to change some environmental files in your conda installation:

Go to: ~/miniconda3/envs/$your_env_name/bin Open the bundle file with a text editor, it should look like the following:

#!/bin/sh
# -*- ruby -*-
# This file was generated by RubyGems.
#
# The application 'bundler' is installed as part of a gem, and
# this file is here to facilitate running it.
#
_=_\
=begin
bindir="${0%/*}"
exec "$bindir/ruby" "-x" "$0" "$@"
=end
#!/usr/bin/env ruby

require 'rubygems'

version = ">= 0.a"

str = ARGV.first
if str
  str = str.b[/\A_(.*)_\z/, 1]
  if str and Gem::Version.correct?(str)
    version = str
    ENV['BUNDLER_VERSION'] = str

    ARGV.shift
  end
end

if Gem.respond_to?(:activate_bin_path)
load Gem.activate_bin_path('bundler', 'bundle', version)
else
gem "bundler", version
load Gem.bin_path("bundler", "bundle", version)
end

You need to change the following line exec "$bindir/ruby" "-x" "$0" "$@" to something that will look like exec "/Users/$your_user_name/miniconda3/envs/sw/bin/ruby" "-x" "$0" "$@". This path represents an OSX path but if you're using a different operational system it might look different for you.

Generating your website and putting it online

Once you have that working you can finally generate your website from the files we've downloaded, using the command:

bundle exec jekyll serve

After you've done this step. You should have your website up and running on your browser under the address http://127.0.0.1:4000/.

To see your changes online you need to git add $files all the generated content by this command, then commit it with a commit message using git commit -m "your message" then push it to your repository using git push.

I don't want to deal with all of this code rot stuff

Fair enough, use HUGO!

If we were on a workshop I'd walk you through these instructions, but since we're not there's no way I do a better job that HUGO's documentation on how to get HUGO up and running.

Same idea as Jekyll but without the gem, bundler overhead (thank god).

Here's a quick summary of what you'll have to do:

Install hugo in your computer, choose a theme, download it, use git init to initialize a github repository, or if you already have a github repository running skip this step. Make your personal changes, run hugo -D to generate the files that will run in your browser. Run git add $files_you_produced, git commit -m "your message" your changes and finally git push.

As an extra step from the Jekyll system though is that you'll have to setup Github Actions, but don't worries, it's as simple as copying/pasting a new file into your repository. This file should be enough. Check the rest of the page if you're stuck in some other step with Github, might be helpful!

Okay, so that's it!

If you have any questions about how to build your website and you're part of WocCodes cohort, you know how to find me! If you just found this and need help, send me an email, I might be able to reply! ^-^

The not so simple web