Lightning Talk: GitHub Pages for project documentation

Lightning talk

5 minutes.

• https://github.com/apetro/github-pages-lightning-talk

What problem are we solving?

• Your project needs a website
• A good website
• A cheap website
• A sustainable website
• A low-risk website

What is GitHub Pages?

• Websites for individuals, organizations, and projects
• Hosted by GitHub
• Generated by Jekyll

GitHub Pages website solution

• Source code GitHub repository
• Generates to website via SaaS Jekyll
• Hosted by GitHub

Free

• Free as in cheapness
• Free as in a free puppy
• Free as in a dogsitter
• Free as in escape route

Features: HTML

• You can simply host a static website.
• Drop in your HTML etc. and GitHub will simply host it for you.

Features: Git

• Versioning
• History

Features: Jekyll

• Jekyll is a static site generator.
• Separate content from presentation.
• From source code, generates the HTML etc., and then GitHub hosts it for you.
• Source code? Text files. Templates. Themes. Pages. Posts. Includes. Styles. Images. Stuff.

Example: oaeproject.org

http://oaeproject.org

Features: Markdown

## What is GitHub Pages?

+ Websites for individuals, organizations, and projects
+ Hosted by GitHub
+ Generated by Jekyll

Features: GitHub: Collaboration

• Branching, merging
• Pull requests

Key feature: edit documentation with code

• Update documentation alongside code documented
• In the same breath
• (Website source in a /docs folder)

Features: GitHub: Web-based editing

• Power tools for developers, and
• Web-based tools for casual or text-file-disinclined editing.

Advantages

• Sustainability
• Transparency
• Openness
• Casual participation
• Exit strategy

What could you build?

• Project website
• Personal website
• Organization website
• Blog
• Project documentation, manual
• Slideware

Apereo examples

• apereo.github.io
• oaeproject.org
• jasig.github.io/uPortal/ ( /docs folder)
• sakaiproject.github.io/sakai/ (gh_pages branch)

Try it

https://pages.github.com/

• New repo
• Existing repo: gh_pages branch
• Existing repo: /docs

This talk

• https://github.com/apetro/github-pages-lightning-talk