Mielke Labs, LLC

Skim

A one-page boilerplate for publishing content on GitHub.

Currently

Introduction

Skim is a one-page boilerplate for publishing technical content on GitHub. It provides the facilities to write exclusively in Markdown and spin-up Jekyll-powered websites.

Browse the sections below and see just how simple it is to roll your own GitHub site for free without using fancy code.

Features and Delighters

Skim is chock-full of nifty doodads and neat delighters, including:

Core Environment

The core for Skim includes:

Browser Compatibility

Below are recommended browsers and platforms for the best usability and performance. Starting from best to worst, we suggest you get the latest version of:

Here’s a comparison of each browser on different OS platforms.

Platform Chrome Firefox Internet Explorer Opera Safari
Android Yes No — No —
iOS Yes — — No Yes
Mac OS X Yes Yes — Yes Yes
Windows Yes Yes Yes Yes No

Apple no longer provides updates for Windows-native Safari browsers. Due to major lapses in critical updates, we do not recommend using Safari on Windows.

Legacy Browsers

Support is limited to whatever legacy browsers can handle. You can try using Modernizr to circumvent compatibility issues, but it’s not perfect.

Prerequisites

Skim requires the minimum version of Ruby below. It also requires Python to run Pygments, but only if you’re planning to use code highlights. Otherwise, you won’t need it.

Ruby

Click here to download and install Ruby. If you have Ruby, but aren’t sure which version, run ruby -v.

Python

Click here to download and install Python. If you have Python, but aren’t sure which version, run python --version.

Pygments

Click here to download and install Pygments. If you have Pygments, but aren’t sure which version, run pygmentize -V.

Download and Clone

The following sections walk you through downloading or cloning Skim from GitHub.

Downloading Skim

There are a number of ways to download Skim. Scroll through the options below and pick one that works best for you.

Tarball Download

Click here or run the command below.

$ curl -OL https://github.com/caleorourke/skim/tarball/master

ZIP Download

Click here or run the command below.

$ curl -OL https://github.com/caleorourke/skim/zipball/master

Cloning Skim

There are also a few ways to clone Skim. Scroll through the options below and pick one that works best for you.

Clone over HTTPS

Run the command below to clone over HTTPS.

$ git clone https://github.com/caleorourke/skim.git

Clone over SSH

Run the command below to clone over SSH.

$ git clone git@github.com:caleorourke/skim.git

Installation

The following is a “how to” for installing Skim and adding runtime dependencies.

  1. Go into the root directory for Skim.
  2. Run gem install bundler to install Bundler.
  3. Run bundle install to load the runtime dependencies.
$ cd skim
$ gem install bundler
$ bundle install

Configuration

The _config.yml is a YAML file for storing and propagating nearly all of the site’s configuration. Anything not handled by it gets handled behind the scenes by metadata. This means you can configure your entire site using just a single file.

Project

  1. Open “_config.yml” using any text editor.
  2. Find “Project”.
  3. Fill in each field with details about your project.
# ==============================
# Project
# ==============================

github:
    title:      Skim
    tagline:    A one-page boilerplate for publishing content on GitHub
    owner:      "Mielke Labs, LLC"
    license:    MIT

Use spaces to separate content. Do not use tabs.

Social

  1. Scroll down to the second group of setting labeled “Social”.
  2. Fill in each field with details about your social network.
# ==============================
# Social
# ==============================

twitter:
    handle:     MielkeLabs
    hashtags:   "css,boilerplate,github-pages"
    text:       "Try Skim, a one-page boilerplate for posting technical content on GitHub."
keywords:       "boilerplate,css,framework,github,github pages,html5,jekyll,liquid,markdown,one-page,redcarpet"

Wrap words in quotes wherever commas are used.

Options

  1. Scroll down to the third group called “Options”.
  2. Type “Y” to enable or “N” to disabled any of the options.
# ==============================
# Options
# ==============================

index:
    enabled:    Y
scrolling:
    enabled:    Y
version:
    enabled:    N

Below is a brief overview of each option.

Option Default Description
Index Y Captures all H1 headers and drops them into a modal
Scrolling Y Enables smooth scrolling animation
Version N Fetches the last pegged release from GitHub and shows it under “Get Started”

For these options, use Y or N. Anything else will disable the option.

Deployment

Learn how to make Jekyll transform raw text into a complete, ready-to-publish static website.

Local Deployment

Run the following command to preview a local instance of your site.

$ jekyll serve

Once Jekyll has started, fire up a browser and type in “localhost:4000” for the web address. This will show the site Jekyll just generated.

Watch Jekyll

If you want to monitor changes and apply updates without having to restart Jekyll, add the --watch option to the command.

$ jekyll serve --watch

Stopping Jekyll

Serve mode lasts forever. It won’t timeout after a period of non-usage. Press “CTRL+C” to stop the service.

Web Deployment

GitHub Pages are public web pages hosted on GitHub’s github.io domain. Jekyll powers it behind the scenes, which makes this a snazzy way to host a free, Jekyll-powered website.

Hosting on GitHub works by storing content in a branch called gh-pages. This means your website can be kept in the same repository as your codebase. This branch, however, will be rendered using Jekyll, and your site will get served up under a subpath of your user pages subdomain, such as username.github.io/project.

Roll Your Own

Start by creating a new orphan branch (e.g. a branch that has no common history with an existing branch) in your repository. The safest way to do this is to make a fresh clone. In this example, we’re going to create one called milk.

$ git clone https://github.com/username/milk.git

The example above has username as a placeholder. This is where you want to type your actual GitHub username.

Once you have a fresh clone, you’ll need to create the new gh-pages branch and remove any content from the working directory.

$ cd milk
$ git checkout --orphan gh-pages
$ git rm -rf .

Next, copy all the content from /skim to your /milk directory.

$ cp -r ~/skim/* ~/milk

Now that you have content in your own directory, you can push it to GitHub.

$ git add .
$ git commit -a -m "first commit"
$ git push origin gh-pages

After you push to gh-pages, your site will be available at username.github.io/milk.

It can take up to ten minutes before your site is available, but in most cases, it’s ready instantly.

Code Organization

The following is a simple introduction to the directory structure and contents for Skim.

Pre-Install

Below is the basic spread for Skim (not including site for Jekyll).

├─ _includes
├─ _layouts
└─ stylesheets

3 directories

Folders beginning with an underscore tell Jekyll to use the content within them to generate your site. They’re not exposed after the site is created, though.

Post-Install

A working environment will have one more directory: site (Jekyll).

├─ _includes
├─ _layouts
├─ _site
└─ stylesheets

4 directories

Directory

Here’s an overview of what each directory does or contains.

Directory Overview
_includes Semantic HTML elements and reusable content
_layouts Reusable templates for specific uses
_site Where Jekyll places generated sites after it’s transformed
stylesheets Static CSS stylesheets in .css format

Useful Resources

Below is nonspecific information written during development that might be useful to some, but not everyone.

Metadata

We harness several metadata tags using GitHub’s metadata feature, albeit not all of them for a number of reasons.

Below is a list of metadata tags we use.

Code Styles

Use the settings below to help unify coding styles across different editors.

indent_style = space
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = false
indent_size = 4

Sublime Text users can configure these settings manually by opening “Preferences > Settings - User”, inserting the lines below, and saving your settings.

{
  "translate_tabs_to_spaces": true,
  "tab_size": 4,
  "ensure_newline_at_eof_on_save": false,
  "default_encoding": "UTF-8",
  "default_line_ending": "lf",
  "trim_trailing_white_space_on_save": true
}

Sublime Packages

We use Sublime exclusively. One of its few drawbacks, though, is it does not include every syntax highlight. To get certain highlights, you have to install them by hand. Use the instructions below to perform the install processes for Jekyll and Liquid.

Package Control, Sublime’s built-in tool, can install these syntaxes. If you already have Package Control, skip the rest of this and start on the next section. If you don’t, this install guide will walk you through all the install options.

Jekyll Packages

  1. Open “Preferences > Package Control”.
  2. Type “Install Package” and hit “Return”.
  3. Type “Jekyll” and hit “Return”.

The Jekyll package includes syntaxes for HTML, JSON, Markdown, and Textile.

Liquid Packages

  1. Open “Preferences > Package Control”.
  2. Type “Install Package” and hit “Return”.
  3. Type “Siteleaf Liquid Syntax” and hit “Return”.

The Liquid package includes syntax for HTML.

Where to Go Next

Here’s a helpful serving of groovy websites that you might find helpful.

License

Our code and documentation is licensed under the MIT license.