Here we cover a few common static site generators and similar solutions. We'll first go over how jquery can be used as a lightweight solution for things like headers and footers that ought to be the same across all parts of your site. Then we'll dive into two of the most popular true static site generators, Hugo and Jekyll.
This guide presupposes some familiarity with the command line. Hugo is a static site generator that utilizes markdown for content and templated html for layout. To get started, first install Hugo (Windows, MacOS, Linux). In your command line you can confirm that hugo is installed by running
hugo version
Once installed, use your command line to change directories to the place
where you would like to create your site, if the name of your project is
my_first_project
, run
hugo new site my_first_project
This will create a new directory called my_first_project to contain your site. If you plan to use this for your course site, you should initialize this folder as your course git repository.
To generate the HTML for your site from layout and content files, you can
run hugo server -D
from your project directory. You can then
view your site, with live changes as you modify files, at
http://localhost:1313/. Unfortunately, Hugo doesn't come with
any theme or content preinstalled, so you will just see a blank page at
this point.
Hugo comes with a community of developers who have made themes as starting
points. You can create your own theme
if you're feeling particularly adventurous. Note that this documentation
is not particularly good. Otherwise, you can use one of the many existing
themes on Hugo's website. These
themes are usually linked to github repositories that you can clone or
download as a zip. If you put that repository into the
themes/
subfolder of your project folder, you will be able to
use that theme. If you add the theme in the subfolder
my_first_project/themes/my_theme
then you can use your theme
by adding it in the configuration file for your site. To do this open the
file my_first_project/config.toml
in your text editor and add
the line theme = "my_theme"
Each theme has documentation on its home page of what types of content +
layouts it comes with built in, and depending on the theme you choose, you
should read through their documentation to understand how to use the theme.
Usually these themes allow for further customization through the
config.toml
file.
That's the basics of getting Hugo up and running. More resources on the directory structure generated for a project and how to add new content or layouts can be found on the Hugo Website.
This script
might be helpful if you'd like to make pushing your site to github easier.
If you put this script in you project directory, and follow the directions
on the linked page, then you only need to run the linked script with
sh publish_to_ghpages.sh
to deploy your site.
This guide presupposes some familiarity with the command line. Jekyll is a static site generator that utilizes markdown for content and templated html for layout, and uses the Ruby language to actually generate the HTML of the static site. To get started, first follow the installation guide for your system.
Jekyll provides a working site out of the box, without having to install themes or add your own layouts/content like Hugo. To create a project run:
jekyll new my_first_project
To build and view the site, run the following in your project directory:
bundle exec jekyll serve --livereload
and then open the url http://localhost:4000.
Adding the --livereload
flag above makes the webpage
automatically refresh whenever you change one of the source files.
You can add new posts by adding files in the _posts
directory,
following the example post there.
If you choose to make your site with Jekyll, you should experiment with different layouts besides the default. Given how much of the boilerplate is created for you through just the lines in the tutorial, we expect a greater level of exploration. You can modify themes or add layouts. The Jekyll documentation is very robust and is a good guide for exploration.
Finally, the Jekyll guide on deploying to Github pages could be helpful if you plan to use this as your course site.