Jekyll

Jekyll is a static site generator. You can browse the documentation on that site, but here are some further distilled tips based on our class on 12 Feb.

For Windows users, I recommend these installation instructions. For Mac and Linux, you can just follow the default quick-start guide on the Jekyll web site.

To begin using Jekyll once it is installed, change to the cloned directory that corresponds to your gitlab repository, something like this:

  • If using Git Bash or Mac terminal: cd ~/Desktop/cs120-NAME
  • If using Command Prompt: cd %HOMEPATH%\Desktop\cs120-NAME

Then run this command, where we specify the name of the subdirectory that Jekyll should create for your new site:

jekyll new assn2

Change into that directory:

cd assn2

Now the site is ready to build or serve. This command:

jekyll build

generates all the files into the _site subdirectory. Don’t edit anything there, because they will be regenerated and overwritten. The html files are hard to use from there directly, because Jekyll assumes it can access stylesheets and such at the top-level of the site, like href="/assets/main.css" and that doesn’t work when using a file:/// URL. So instead, try this:

jekyll serve

That will generate all the files, and start a web server so you can view the generated site at http://localhost:4000/. Also, it will wait around until it detects a saved change in one of the source files, and then it regenerates automatically. To stop the server and get back to your prompt, hit control-C.

Finally, I wanted you to edit the layout of the site. The newest versions of Jekyll do not automatically create _includes and _layout directories. Instead, your _config.yml refers to a default theme, called minima, like this:

theme: minima

You can comment out that line (using #), but now you’ll have no default theme. The simplest way to customize the files used by minima is to copy them into your directory. You can find them with this command:

bundle show minima

That prints a path on your system, like C:\Ruby22\lib\ruby\blahblah and you can navigate there in your Finder/Explorer to find the files. In the named directory, you should see _includes, _layouts, _sass, and assets. Copy all four of these into your project directory. Then it should regenerate the site as it did with the minima theme. But you can explore those files and edit them to adjust the layout site-wide.