I first started using Jekyll a static site generator, early 2016.
The following isn’t a guide for how to use Jekyll, but instead almost a guide for me to quickly make updates to this site, and learn/document things on the way.
To learn how Jekyll works I read, or more realistically skimmed over tutorials. However, what helped me the most was reverse engineering sites generated using Jekyll. Before that I tried using themes that people had created but many of them felt broken.
Posts for Nearly Everything
Within each blog post there is a YAML front matter block that will be processed by Jekyll as a special file. In order to communicate to Jekyll add three dashes before and after the front matter. Below is an example:
--- layout: article title: "How I'm using Jekyll for this site." excerpt: "Documenting my approach to using and learning Jekyll." categories: blog tags: [Jekyll, web development, style guide] image: header: testfeature.png teaser: doggyrobes.jpg featured: true modified: 2016-06-15 ---
Pages for Everything Else
Content that doesn’t need to be ordered chronologically or grouped in any way becomes a page. To keep things nice and tidy I place all of the source
.html files into a
_pages directory and assign permalink overrides in the YAML Front Matter of each.
An architecture like this helps centralize the content so you’re not poking around trying to locate files. Meaningfully naming files should be the goal. Avoid patterns like
/about/index.md as it makes distinguishing between multiple
index.md files harder.
project-name/ ├── _assets/ ├── _includes/ ├── _layouts/ ├── _pages/ | ├── 404.md | ├── about.md | ├── blog.md | ├── home.md | ├── portfolio.md | ├── resume.md | ├── sitemap.md | └── tag.md ├── _posts/ ├── images ├── _config.yml └── Gemfile
Tools Needed to Get the Site Up and Running
Installing Ruby, Bundler, and Ruby Gems are essential to getting this site running.
It didn’t take long to fully embrace Bundler but mainly because it’s what everyone else is doing. Bundler is the official way to install Jekyll. Tt wasn’t that big of a leap for me to start using a
Gemfile to manage all dependencies. To do that:
bundle initto create an empty
gem 'jekyll'and any other gems to the
Below is what the gemfile for this site looked like as of 6/29/2017.
#Gemfile source 'https://rubygems.org' gem 'wdm', '~> 0.1.0' if Gem.win_platform? gem 'mini_magick' gem 'autoprefixer-rails' gem 'uglifier' # Jekyll gem 'jekyll' gem 'jekyll-archives' gem 'jekyll-tagging-related_posts' gem 'jekyll-sitemap'
Now when running
bundle install each of the gems specified above are installed and a
Gemfile.lock is created listing all of the dependencies.
In my experience it is extremely easy to break a gem resulting in the entire site to stop working. In other words (I know it’s obvious) but backup this file before installing a new update.
bundle exec jekyll serve
bundle exec jekyll build