programming pages is a theme for Jekyll. It is a collection of files designed to be dropped into your project’s documentation folder.

As a shortcut, you can have GitHub manage the installation of theme files by using the remote_theme key in your site config file.

• Usage
  • Running locally
• Other installation methods
  • Install via remote theme
  • Install via Ruby Gem
  • Install via file copy

Usage

To use programming pages with GitHub pages, the simplest method is to require it as a remote theme in your _config.yml file (remove any other theme: or remote_theme: entries).

remote_theme: pixeldroid/programming-pages

See Other installation methods for additional options.

Then use the theme to:

1. Author your content
2. Publish to GitHub Pages
3. (optionally) Customize the theme to taste

Running locally

Info
Ruby is required to run locally. Older versions may work, but you probably want to match what GitHub is using.

Setting up locally for testing a GitHub pages target is best done via Bundler:

1. Ensure your Gemfile includes the following (these may be the only lines you need):

   source 'https://rubygems.org'
   
   gem 'github-pages'
   

2. Retrieve dependencies into a local bundle:

   $ bundle install
   

3. Build and serve the site:

   $ bundle exec jekyll serve --source ./docs --layouts ./docs/_layouts
   

Other installation methods

There are three ways to install the theme for your site:

1. via the jekyll-remote-theme plugin (for GitHub Pages hosting)
2. via the programming-pages Ruby gem (for self-hosted sites)
3. by downloading a release of theme files directly and adding them to your site (for capturing dependencies or making custom modifications)

Install via remote theme

1. Ensure the jekyll-remote-theme gem is part of the dependency chain of your Gemfile (it will be if you are requiring github-pages >= 171):

   source 'https://rubygems.org'
   
   gem 'github-pages'
   

   $ bundle exec gem dependency | grep 'Gem jekyll-remote-theme'
   Gem jekyll-remote-theme-0.3.1
   

2. Specify the remote theme gem in your _config.yml:

   remote_theme: pixeldroid/programming-pages
   

3. Retrieve dependencies into a local bundle:

   $ bundle install
   

4. Build and serve the site:

   $ bundle exec jekyll serve --source ./docs --layouts ./docs/_layouts
   

Install via Ruby Gem

1. Require the programming-pages theme gem in your Gemfile (replace the github-pages dependency):

   - gem 'github-pages'
   + gem 'programming-pages'
   

2. Specify the theme in your _config.yml:

   theme: 'programming-pages'
   

3. Retrieve dependencies into a local bundle:

   $ bundle install
   

4. Build and serve the site:

   $ bundle exec jekyll serve --source ./docs --layouts ./docs/_layouts
   

Install via file copy

1. Download a zipfile of a programming pages release from GitHub:

   $ API='https://api.github.com/repos/pixeldroid/programming-pages/releases/latest'; \
     ZIP="$(curl -sL $API | jq -r '.assets[].browser_download_url')"; \
     curl -LO $ZIP && unzip "$(basename $ZIP)"
   

2. Unzip it into your project’s documentation folder:

   $ mkdir -p docs && mv programming-pages/* docs/ && rmdir programming-pages
   

3. Build and serve the site:

   $ bundle exec jekyll serve --source ./docs --layouts ./docs/_layouts