g2forge/charcoal

A dark theme for jekyll

layout	title	permalink
home	Charcoal Theme	/index.html

About

Charcoal is a dark theme for jekyll.

Usage

The theme is available as open source under the terms of the MIT License. It is distributed as a ruby gem.

Installation

Add this line to your Jekyll site's Gemfile:

gem "jekyll-theme-charcoal"

If you're building a standard jekyll site (without github pages), add this line to your Jekyll site's _config.yml:

theme: jekyll-theme-charcoal

If instead you're using github pages, add this line to your Jekyll site's _config.yml:

remote_theme: g2forge/charcoal

And then run:

user@localhost ~/my-awesome-site
$ bundle install

Layouts

• default is the base layout, contianing only a header and content.
• home is ideal for a landing page, as it includes not only the content, but also a blog roll with RSS link and social links as configured below.
• page is currently no more than a repackaged default.
• post is currently no more than a repackaged default, except that posts are indexed and listed on the home page.

In addition to the standard jekyll front matter, the charcoal theme will use the following variables on each page:

bare: true                            # Make this page by not displaying author information, and ensuring there's no table of contents
toc: true                             # Adds a table of contents to the left sidebar of the page
credits: true                         # Adds credits for the page including the author and date to the title
author_name: Greg Gibeling            # Sets the name of the author
author_url: https://github.com/gdgib/ # An optional link to a page specific to the author

404

You should copy our 404 page into your site. Ours is configured to display in the most friendly manner.

Customization

You can configure a default author for pages and posts in your _config.yml:

image: /images/image.jpg              # Adds a small thumbnail image to the site header (a picture or logo)
bare: false                           # Determines whether pages are bare by default
toc: true                             # Determines whether to adds a table of contents to the left sidebar of the page by default
credits: true                         # Determines whether credits including the author and date to the title of the page by default
author_name: Greg Gibeling            # Sets the name of the default author, which can be overriden on each page
author_url: https://github.com/gdgib/ # An optional link to a page specific to the default author, can be overriden on each page

As in minima you can add links to the accounts you have on other sites, with respective icon, by adding one or more of the following options in your _config.yml:

twitter_username: jekyllrb
github_username:  jekyll
dribbble_username: jekyll
facebook_username: jekyll
flickr_username: jekyll
instagram_username: jekyll
linkedin_username: jekyll
pinterest_username: jekyll
youtube_username: jekyll
googleplus_username: +jekyll
rss: rss

mastodon:
 - username: jekyll
   instance: example.com
 - username: jekyll2
   instance: example.com

Includes

Below is a list of the includes designed to be used manually. The theme itself uses several includes which are automatically used that you may also wish to explore.

About Image

The about_image.html include will generate a small section including a profile picture on the left and some HTML content on the right. While intended for talking about, for example, the author of a webite we encourage you to get creative with this.

Usage:

{% raw %}
{% capture about %}
Some content goes here
{% endcapture %}
{% include about_image.html image_src="images/Profile.jpg" image_alt="My awesome profile picture" content=about %}
{% endraw %}

Parameters:

• image_src (string) - The page or URL of the image to display
• image_alt (string) - The alternate text of the image
• content (text) - The content to display to the right of the image

Contributing

Issues and pull requests are welcome on github.com/g2forge/charcoal.

Development

To set up your environment to develop this theme, run:

user@localhost ~/charcoal
$ bundle install

In order to test your changes locally run:

user@localhost ~/charcoal
$ bundle exec jekyll serve

After that you can see your handiwork by viewing this page with any modifications you've made. Please note that you will need to reload the page after changes as is normal with jekyll.

Build

To build the gem and install it for local development testing run:

user@localhost ~/charcoal
$ gem build ./jekyll-theme-charcoal.gemspec
$ gem install ./jekyll-theme-charcoal-<VERSION>.gem

Once you are satisfied that this version is ready run:

user@localhost ~/charcoal
$ gem push ./jekyll-theme-charcoal-<VERSION>.gem

After this you will need to:

• Git tag the release
• Update the gemspec version
• Update the maven version
• Add a new milestone on github and any issue tracking systems

Inspiration

This theme is based on the following:

• midnight by Matt Graham - design, structure, fonts, etc
• minima by Jekyll - including social icons and design
• jekyll-toc by Vladimir Jimenez - for the fancy table of contents

charcoal's Issues

Header breaks view point returned from toc

Hello, charcoal looks great but I have a small issue with header obstructing page elements after using TOC.

I describe this issue and potential steps in fixing it below.

• Issue
  Whenever you use toc/url navigation like: www.g2forge.com/charcoal/#about-image
  Part of returned view point (and direct descendant) is obscured by page header (div#header).

• Expected behavior:
  Returned view point after url navigation (/#name_of_target) should present said element unobstructed just under page header.

• Observed on:
  Google Chrome Version 73.0.3683.10 (Official Build) dev (64-bit)
  Microsoft Edge 44.17763.1.0

• Example fix:

window.addEventListener('hashchange', function(){
   document.documentElement.scrollTop = document.documentElement.scrollTop - $("div#header").height() - 5; 
}, false);

Number (static 5) is an extra spacing between header and top of navigated element for aesthetic purpose. Fix only targets TOC navigation, does not fix URL navigation (example: other site referring to #id)
I'm not sure if this issue can be fixed without use of JS

Edit: Rough fix with taking care of redirect from outside of the site issue

realignViewPoint = function() {
    if (window.location.href.indexOf("#") > 0) {
        document.documentElement.scrollTop = document.documentElement.scrollTop - $("div#header").height() - 5;
    }
}
window.addEventListener('hashchange', realignViewPoint, false);
window.addEventListener('load', realignViewPoint, false);