programming-pages

a Jekyll theme for publishing code documentation to GitHub pages.

View demo View Github

installation

as a remote theme

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

plugins:   - jekyll-remote-theme remote_theme: pixeldroid/programming-pages

as a gem

Follow the Jekyll directions for installing a gem-based theme

Gemfile:

gem 'programming-pages'

_config.yml:

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/)

usage

first:

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

building

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

first:

  1. install jekyll and the github-pages gem: bundle install

rake docsopen http://localhost:4000/

generating the semantic ui files

first:

  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

first

  1. ensure you can build jQuery (requires nodejs, grunt): grunt default

grunt custom:-ajax,-wrap remove_map_commentcp /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 https://github.com/jquery/jquery#modules)

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

excluded
  • ajax
  • wrap
required
  • 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

GitHub