whiteglass
whiteglass
Minimal, responsive Jekyll theme for hackers.
Installation
Add this line to your Jekyll site’s Gemfile:
gem "jekyll-whiteglass"
And add this line to your Jekyll site’s _config.yml
:
theme: jekyll-whiteglass
And then execute:
bundle
Or install it yourself as:
gem install jekyll-whiteglass
Quick Start
- Go to yous/whiteglass-template.
- Click “Use this template” button, and then create a repository.
- Change the options defined in _config.yml. See Configuration section under whiteglass-template.
- Push some content, then GitHub Actions will generate the site.
Manual Setup
-
Generate a new Jekyll blog:
jekyll new blog --skip-bundle cd blog
-
Edit
Gemfile
to use whiteglass theme:gem "jekyll-whiteglass"
-
Edit
_config.yml
to use whiteglass theme and its plugins:theme: jekyll-whiteglass plugins: - jekyll-archives - jekyll-paginate - jekyll-sitemap permalink: /:year/:month/:day/:title/ paginate_path: /posts/:num/ paginate: 5 jekyll-archives: enabled: - categories - tags layout: category_archives permalinks: category: /categories/:name/ tag: /tags/:name/
-
Copy
index.html
,about.md
,archives.md
,feed.xml
,robots.txt
,_data/i18n.yml
, and_data/navigation.yml
from the theme:rm index.md curl -L -O "https://github.com/yous/whiteglass/raw/master/{index.html,about.md,archives.md,feed.xml,robots.txt}" curl -L --create-dirs -o _data/#1 "https://github.com/yous/whiteglass/raw/master/_data/{navigation.yml,i18n.yml}"
-
Install gems and you’re good to go! The blog will be available on
http://127.0.0.1:4000
.bundle install bundle exec jekyll serve
Upgrading
From Versions < 1.9.1
Copy
_data/i18n.yml
from the theme.
Deployment to GitHub Pages using Travis CI
This theme uses jekyll-archives gem which is not supported by GitHub Pages. If you want to use full features like categories and tags, I recommend you to use Travis CI or other CI services.
To deploy using Travis CI, first copy the .travis.yml
of this repository. You can change target-branch
(gh-pages
by default) and
on.branch
(master
by default) as you want. If you want further
customization, see Travis CI’s documentation page.
You’ll see there’s github-token: $GITHUB_TOKEN
, and this is what you should
configure. Go to your personal access tokens
page, and generate new token with public_repo
or repo
permission as you
need. Then go to Travis CI’s settings page of your repository, and add a new
environment variable GITHUB_TOKEN
with the value of the token you generated.
Usage
Customization
To override the default structure and style of whiteglass, simply create the
concerned directory at the root of your site, copy the file you wish to
customize to that directory, and then edit the file. e.g., to override the
_includes/footer_content.html
file to add
contents to footer, create an _includes
directory, copy
_includes/footer_content.html
from jekyll-whiteglass gem folder to
<your-site>/_includes
and start editing that file.
For example, you can add favicons to _includes/head_custom.html
:
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="apple-touch-icon" sizes="76x76" href="/apple-touch-icon-76x76.png">
<link rel="apple-touch-icon" sizes="120x120" href="/apple-touch-icon-120x120.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-touch-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon-180x180.png">
The site’s default CSS is in the gem itself,
assets/main.scss
. To override the default CSS, the file
has to exist at your site source. Do either of the following:
- Create a new instance of
main.scss
at site source- Create a new file
main.scss
at<your-site>/assets/
- Add the frontmatter dashes, and
- Add
@import "whiteglass";
, to<your-site>/assets/main.scss
- Add your custom CSS
- Create a new file
- Download the file from this repo
- Create a new file
main.scss
at<your-site>/assets/
- Copy the contents at
assets/main.scss
onto themain.scss
you just created, and edit away
- Create a new file
- Copy directly from jekyll-whiteglass gem
- Go to your local jekyll-whiteglass gem installation directory (run
bundle show jekyll-whiteglass
to get the path to it) - Copy the
assets/
folder from there into the root of<your-site>
- Change whatever values you want, inside
<your-site>/assets/main.scss
- Go to your local jekyll-whiteglass gem installation directory (run
Locale
site.lang
is used to declare the primary language for each web page within the
site.
lang: en-US
sets the lang
attribute for the site to the United States flavor
of English, while en-GB
would be for the United Kingdom style of English.
Country codes are optional and the shorter variation lang: en
is also
acceptable. You may want to write a post in different language, then add lang
attribute to the frontmatter of that post:
layout: post
title: "안녕하세요"
lang: ko
The date format and other fixed strings are translated using the _data/i18n.yml
file. If your language is not yet included, feel free to open a pull request.
Description
site.description
describes the site. This is mainly used in meta descriptions
for improving SEO. Also, you can set description
attribute for each post:
layout: post
title: Awesome Post
description: This is an awesome post.
If you don’t specify post.description
, then post.excerpt
will be used if it
exist.
External URL
external-url
turns the title of your post to a link. Specify a URL which you
want to link to.
layout: post
title: Jekyll whiteglass theme
external-url: https://github.com/yous/whiteglass
Then the title of your post would look like a link with text
Jekyll whiteglass theme →
. This also applies to your blog feed.
Category
Each post can have categories
attribute. It can be a string or an array. This
will be displayed on index, archive and each post, and provide a link to the
archive of category.
layout: post
title: Awesome Post
categories: Misc
layout: post
title: Another Awesome Post
categories:
- Misc
- Idea
Tag
Each post can have tags
attribute. It can be a string or an array. This will
be displayed on index, archive and each post, and provide a link to the archive
of tag.
layout: post
title: Awesome Post
tags: food
layout: post
title: Another Awesome Post
tags:
- food
- trip
Feed
Create <your-site>/feed.xml
with:
---
layout: feed
---
If you want to use another path for feed, you can specify a non-default path via your site’s config.
feed:
path: atom.xml
Then create <your-site>/atom.xml
with the same content of feed.xml
above.
Comments
whiteglass provides the ability to include your favourite commenting service, like Disqus or Isso.
To enable comments on pages and posts:
- Overwrite the
_includes/custom_comments_provider.html
with your custom provider of comments. - Add
comments: true
to your_config.yml
.
To disable comments on certain pages or posts specify comments: false
in the front matter of the page or post.
Metadata for SEO
Keywords
Each post can have keywords
attribute. This is a comma-separated list which is
used in meta descriptions for improving SEO.
layout: post
title: How to configure jekyll-whiteglass
keywords: jekyll, whiteglass, github pages
YAML list is also available:
keywords:
- jekyll
- whiteglass
- github pages
site.twitter_username
setstwitter:site
andtwitter:creator
meta tagsite.twitter_image
setstwitter:image:src
meta tagpage.twitter_card.type
setstwitter:card
meta tag (default:summary
)- If
page.twitter_card.type
isgallery
, it setstwitter:image0
,twitter:image1
,twitter:image2
andtwitter:image3
meta tags withpage.twitter_card.image
,page.twitter_card.image1
,page.twitter_card.image2
andpage.twitter_card.image3
, respectively - If
page.twitter_card.type
isphoto
,page.twitter_card.width
setstwitter:image:width
meta tag andpage.twitter_card.height
setstwitter:image:height
meta tag
- If
page.twitter_card.creator
setstwitter:creator
meta tag. It overridessite.twitter_username
page.twitter_card.image
setstwitter:image:src
meta tag ifpage.twitter_card.type
is notgallery
. It overridessite.twitter_image
site.facebook_app_id
setsfb:admins
meta tagsite.facebook_page
setsarticle:author
meta tagsite.facebook_image
setsog:image
meta tagpage.facebook.image
setsog:image
meta tag. It overridessite.facebook_image
Navigation
To define header links, add titles and URLs under the main
key in
_data/navigation.yml
:
main:
- title: "About"
url: /about/
- title: "Archives"
url: /archives/
- title: "GitHub"
url: https://github.com/yous/whiteglass
Enabling Google Analytics
To enable Google Analytics, add the following lines to your Jekyll site:
google_analytics: UA-NNNNNNNN-N
For Google Analytics 4, add the following lines:
google_analytics: G-NNNNNNNNNN
Replace N
s with your specific ID.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/yous/whiteglass. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Development
To set up your environment to develop this theme, run bundle install
.
Your theme is setup just like a normal Jekyll site! To test your theme, run
bundle exec jekyll serve
and open your browser at
http://localhost:4000/whiteglass/
. This starts a Jekyll server using your
theme. Add pages, documents, data, etc. like normal to test your theme’s
contents. As you make modifications to your theme and to your content, your site
will regenerate and you should see the changes in the browser after a refresh,
just like normal.
License
The theme is available as open source under the terms of the MIT License.