A starter template for a Jekyll site
This is a template for creating a website with Jekyll. We use it at Electric Book Works.
Usage
This site is built with Jekyll. Follow the installation and running instructions for Jekyll to install and run it locally.
Building the live website
This project can be set up to use GitHub Pages as its live web host. This means that any changes committed to the master branch of this repository will be built into the live site immediately.
If this changes in future, and you want to build HTML to place manually on a server:
- To set up, run
bundle install
at least once in the repo root to install the Ruby gems we need. - From the Terminal, run
bundle exec jekyll serve --baseurl=""
. - Open your browser to
127.0.0.1:4000
and test the site. - If all's well, copy the contents of the
_site
folder to thepublic_html
folder (or equivalent) of the live webserver.
Editing content
Once you've created your own project repository from the files in this template, follow these editing guidelines to change your site content.
How to make changes
If you're confident with Git, you can clone this repo and edit locally.
Otherwise, the easiest place to edit text is on prose.io. Prose is a simple text editor for editing files on GitHub. If you don't have write access to the original project, your changes will be sent to the repo administrator, who can merge them into the live site.
To create your own copy of the site to play with:
- Fork the repository on GitHub.
- In your fork's repository settings, activate GitHub Pages.
- On GitHub, open the
_config.yml
file and change thebaseurl
line tobaseurl: "/jekyll-starter"
. - Edit your files on GitHub.com directly, or use prose.io. When you use prose.io, make sure you're editing your fork, and not the original repository.
- Your site and changes you make will be live at
username.github.io/jekyll-starter
, whereusername
is your GitHub username. - To submit your changes to the original repository, create a Pull Request on your repository on GitHub.
Main site pages
The site's main pages are markdown files in the project root. The home page is index.md
.
Data and settings
Edit site settings and the menu (navigation) in the files in the _data
directory.
- The
settings.yml
file is where you set things like the site's name, tagline, description, default image, canonical URL and Google Analytics ID. - Create your nav menu in the
menu.yml
file. There are code comments there to guide you. - Edit (or translate) phrases used in the site's HTML templates in
locales.yml
. If you change the language of your site insettings.yml
, then change the phrases inlocales.yml
for that language subtag (e.g.fr
for French).
Images
To add an image, you can use standard kramdown syntax, but then you'll be missing a key feature of this template: your user's browser won't fetch the size of image best suited to their device. Instead, use this image tag:
{% include image file="foobar.jpg" %}
where foobar.jpg
is the original filename of the image.
If necessary, you can add class
or alt
attributes to the image, too:
{% include image file="foobar.jpg" class="example" alt="An example image." %}
(You can also use src="foobar.jpg"
instead of file="foobar.jpg"
, if you're used to standard HTML img
syntax, which uses src
.)
Generating images
It's best practice to let a user's browser fetch a size of image that suits their device (e.g. smaller versions of images on their phone). This template lets you do that.
For each image, the site needs four sizes: a default size and then 320-, 640- and 1024-pixel-wide versions. These need to be saved in the images
folder. You can create these versions manually, but it's easier to use a script to generate them automatically. If you're working on a copy of the site on your own, local machine, you can do this. (You can't do this when you're using an online editor like prose.io.)
To generate the variously sized versions of images for different devices, place the original, high-res versions of your images in _source/images
. Then from the Terminal or Command Prompt, in the project root, enter gulp
.
The gulp script will process all the images in _source/images
and save the various sizes in images
for you.
Of course, for this to work you must have set up your computer beforehand:
- Install Node.js.
- Install gulp.
- Install GraphicsMagick.
- Run
npm install
once from the Terminal or Command Prompt, in the project root.
Captions
To create a caption for an image, make an image the first line of the paragraph that is the caption text, and give the paragraph the image-with-caption
class tag, like this:
{% include image file="great-expectations.jpg" %}
The cover of Great Expectations
{:.image-with-caption}
This also works with regular markdown image syntax:
![]({{ site.baseurl }}/images/great-expectations.jpg)
The cover of Great Expectations
{:.image-with-caption}
Gallery
To create a gallery of images that tiles on the page, add all the images one after the other, each on a new line. Then add a {:.gallery}
tag on the last line after the images.
{% include image file="sam.jpg" %}
{% include image file="pat.jpg" %}
{% include image file="cam.jpg" %}
{:.gallery}
By default, a gallery fits three images in a row on a large screen. To get two, larger images per row, use {:.gallery-larger}
instead of {:.gallery}
. Or give the specific images you want larger a large
class:
{% include image file="toni.jpg" class="large" %}
{% include image file="phil.jpg" class="large" %}
{% include image file="sam.jpg" %}
{% include image file="pat.jpg" %}
{% include image file="cam.jpg" %}
{:.gallery}
You may need to add empty placeholder images to balance a gallery that has one or two images on the last line, for multiples of three (or two if using large
or gallery-larger
):
{% include image file="toni.jpg" %}
{% include image file="sam.jpg" %}
{% include image file="pat.jpg" %}
{% include image file="cam.jpg" %}
![](){:.placeholder}
![](){:.placeholder}
{:.gallery}
Drafts
You can keep unfinished drafts of posts in _drafts
. These have no effect on the built site.
Social sharing and page info
When you share a link on a site like Facebook or Twitter, that site shows a preview of the page you're linking to. Usually, it shows a title, an image and a description.
This information is defined for each page in its 'YAML frontmatter', the section at the top of each markdown page between three hyphens: ---
. For example:
---
title: "Team"
description: "Our team of Wookiees are leaders in the field of starship repair and maintenance."
image: "chewie.jpg"
---
Note that the content or value for each item is inside straight quotation marks, so that Jekyll knows where it starts and ends.
If you don't add a description or image for a page, the fallback is what's in _data/settings.yml
.