programming-pages

a Jekyll theme for publishing code documentation to GitHub pages

See programming pages used to document itself here: https://pixeldroid.github.io/programming-pages/

installation | usage | building | contributing

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.

1. Author documentation
2. Push to GitHub
3. Visit your documentation site at https://<username>.github.io/<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.

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 docs
open 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_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 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

contributing

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