a jekyll theme for publishing code documentation to GitHub pages


a Jekyll theme for publishing code documentation to GitHub pages

See programming pages used to document itself here:

installation | usage | building | contributing


as a remote theme

Specify pixeldroid/programming-pages as your remote theme in _config.yml:

  - jekyll-remote-theme

remote_theme: pixeldroid/programming-pages

as a gem

Follow the Jekyll directions for installing a gem-based theme


gem 'programming-pages'


theme: programming-pages

as a local copy of the files

  1. Download the latest release
  2. Extract it into your project under a folder of your choice (e.g. docs/)



  1. Configure a publishing source for GitHub Pages so GitHub knows where to find your documentation.
  1. Author documentation
  2. Push to GitHub
  3. Visit your documentation site at https://<username><project>
  4. repeat

If you just want to use the theme, you can stop reading here. The directions below are only useful if you're interested in building the theme from source.


programming pages depends on Jekyll, Semantic UI, and jQuery. The dependencies are all captured and coordinated in the source of this project, but if you want to update a dependency or change its configuration, you'll need to be able to build them from source.

building the static site locally


  1. install jekyll and the github-pages gem: bundle install
rake docs
open http://localhost:4000/

generating the semantic ui files


  1. ensure you can build semantic ui (requires nodejs, npm, gulp): gulp build
  2. check out the programming-pages branch of the pixeldroid fork of semantic ui
rake semantic['/path/to/programming-pages-semantic']

semantic ui modules

The Semantic UI modules required by this project are declared in build/semantic/semantic.json.

generating the jQuery file


  1. ensure you can build jQuery (requires nodejs, grunt): grunt default
grunt custom:-ajax,-wrap remove_map_comment
cp /path/to/jquery/dist/jquery.min.js /path/to/programming-pages/_includes/scripts/jquery/jquery-<version>.custom.min.js

Don't forget to update assets/site.js with the new filename.

jQuery modules

Smaller custom subsets of the jQuery library can be built by excluding unwanted modules. (see

This project excludes the following unused modules to reduce file size:

  • ajax
  • wrap
  • attr
  • classes
  • core
  • css
  • data
  • deferred (required for effects)
  • deprecated (for jQuery Address's use of bind)
  • dimensions
  • effects
  • events
  • filtering
  • init
  • manipulation
  • offsets
  • parseHTML
  • prop
  • ready
  • traversing
  • val


Pull requests for improved documentation, bug fixes and useful features are all welcome. :gift_heart: