Maker likes to build stuff by hand or with tools.

Jekyll Tips and Tricks

Getting Started

The command jekyll new <PATH> installs a new Jekyll site at the path specified (relative to current directory).

To install the Jekyll site into the directory you’re currently in, run jekyll new. If the existing directory isn’t empty, you can pass the –force option with jekyll new . --force.
jekyll new automatically initiates bundle install to install the dependencies required. (If you don’t want Bundler to install the gems, use jekyll new myblog --skip-bundle.)
By default, the Jekyll site installed by jekyll new uses a gem-based theme called Minima. With gem-based themes, some of the directories and files are stored in the theme-gem, hidden from your immediate view.
We recommend setting up Jekyll with a gem-based theme but if you want to start with a blank slate, use jekyll new myblog --blank
To learn about other parameters you can include with jekyll new, type jekyll new --help.

About Bundler

Bundler packages ruby gems needed for your project. gem install bundler installs the bundler gem through RubyGems. You only need to install it once - not every time you create a new Jekyll project.

The Gemfile and Gemfile.lock files inform Bundler about the gem requirements in your site. If your site doesn’t have these Gemfiles, you can omit bundle exec and just run jekyll serve.

When you run bundle exec jekyll serve, Bundler uses the gems and versions as specified in Gemfile.lock to ensure your Jekyll site builds with no compatibility or dependency conflicts. In some environments you may need to install WebBrick to serve to your local environment by using this commend: bundle add webrick.

Blog Posts

Blog posts are stored in the _posts folder inside your Jekyll project. The project layout should look something like this:

├── assets      # images and other fixed assets go here
├── _includes
├── _layouts
├── _pages
└── _posts      # blog posts go here

Jekyll requires blog post files to be named according to the following format:

YEAR-MONTH-DAY-title.MARKUP

YEAR is a four-digit number
MONTH and DAY are both two-digit numbers, and
MARKUP is the file extension representing the format used in the file, e.g. html or markdown.

Each post should have the necessary front matter, e.g.

---
layout: post
title: 'Unicorns Make Great Hobby Horses'
descripton: 'This post is made of unicorn flatulence.'
date: 2022-08-15 21:02:56 -0500
author: abigail
image: assets/images/unicorn.jpg
categories: [hobbies, unicorns]
tags: [pink, shiny]
featured: false
hidden: false
rating: 4.75
---

After the front matter, you can begin your post in your markup language of choice.

About Markdown

Documentation for markdown can be found at daringfireball.com.

Adding Images

It’s pretty easy to add pictures too.

![walking](/assets/images/8.jpg)

walking

Full HTML

Perhaps the best part of Markdown is that you’re never limited to just Markdown. You can write HTML directly in the Markdown editor and it will just work as HTML usually does. No limits! Here’s a standard YouTube embed code as an example:

Spoiler Warnings

You might not want your readers to know something that might spoil their experience later. For this, you can use a css class to hide the details.

<span class="spoiler">My hidden sentence or paragraph here.</span>

WSL Lessons Learned

When running locally on Windows Subsytem for Linux, I found that the ruby runtime would often hang unrecoverably with inactivity. To solve this I use the following additional arguments.

bundle exec jekyll serve --force-polling --livereload

Another annoyance I have encountered is that sometimes the terminal application will crash, leaving your sessions active and there is no way to get back to my sessions. I have been able to kill the orphaned Ruby or other processes, but this not convenient. I have started to use Tmux as much as possible, which allows me to reattach to sessions after such crashes.

Reference Lists

Another way to insert links in markdown is using reference lists. You might want to use this style of linking to cite reference material in a Wikipedia-style. All of the links are listed at the end of the document, so you can maintain full separation between content and its source or reference.

- [RStudio Devtools][1]
- [testthat][2]
- [More unit test examples][3]

[1]: https://stackoverflow.com/users/214446/mb21
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html

Baker's Acre