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. 💝