This is a mini shortcut and reference guide on using Jekyll on GitHub Pages as a blogging platform. The page is a work in progress, and to be perfectly honest, is mostly here so that I remember how to update my site.
Jekyll is a Ruby-based static website generator that can be used for publishing websites of various shapes and sizes.
Jekyll is the engine that powers GitHub pages so based on the transitive properties of internet science Jekyll is powering this very page that you are reading.
Know Before You Go
There are a few key concepts or technologies that you should be aware of as you progress through this journey.
The links are here for reference, but you do not have to detour to learn everything about everything before launching a site using Jekyll.
TODO: add link on launching a site on GitHub pages using Jekyll.
- Github Pages
- Liquid Templating Language
to bake an apple pie, you must first invent the universe. -carl sagan
GitHub Pages - Getting Started
GitHub Pages Reference
Great Reference Guide
Let’s Talk Tech
Basic Directory Structure:
|_data||Location for any data that can be referenced in the site. Typically in json, yml, or csv format|
|_drafts||Drafts are saved locally but not checked in to version control.|
|_includes||sidebars and headers|
|_posts||posts go here|
|_site||generated website will go here. don’t touch this. this should be in your .gitignore if hosting on GitHub Pages|
What’s Up GitHub?
The GitHub Pages - Getting Started guide is a good place to start if you are publishing on GitHub. It’s free and if you are looking to get something online fast, there are a handful of pre-built templates that you launch in 5 minutes and a few clicks from the Settings page of your repository.
The front matter is a small section of YAML at the very start of a post, that includes meta information about the post such as the layout type, title, and categories.
--- layout: post | page title: jekyll revisited | so meta | page name here categories: [tech] description: tell me about the page ---
Note: You can also leave the front matter blank! Just include the triple dashes so that the page will be processed by Jekyll, like so:
You can also add custom variables the the front matter that will display on the page layout. For example, if you add
author: guestauthor to the front matter, you can then reference that variable in the layout html document using
page.author enclosed in double curly brackets.
To Add a New Post
To add new posts, simply add a file in the
_posts directory that follows the convention
YYYY-MM-DD-name-of-post.ext and includes the necessary front matter. “ext” will usually be “.md” for Markdown.
To add tags to posts, add the following to the Jekyll Front Matter tags: [demo, dbyll, dbtek, sample2]
To Add Pages
To add new pages, simple add a file in the
_pages directory that includes the necessary front matter. The extension will usually be “.md” for Markdown.
These pages will then be available on the site. Use the base directory and reference the page without the extension. For example,
_pages/about.md will be available on
@TODO Fix the highlight type and explain
Footnotes: The shortcuts and details above were compiled from various Jekyll and theme reference guides.
Here’s a cool look at the evolution of GitHub pages: https://blog.github.com/2015-04-27-eight-lessons-learned-hacking-on-github-pages-for-six-months/