Friday, May 5, 2017

Github pages, fast free static sites on github.

GitHub pages, fast, free, static sites on GitHub.

Looks like it has been almost a year since I blogged anything here. I have a bunch of stuff I wanted to write about but haven't gotten around to it.

On a related note, I've started playing with github pages. These aren't easy to explain if you aren't coming from the right place. It could probably be said this is of most interest to developers. However these are probably of most interest to anyone who likes to use some flavor of markdown to quickly and easily edit text.

GitHub's documentation pages for this are a bit scattered.  They don't really get to the point. Hopefully this won't sound like an ad.

GitHub Pages - What they are

  • A free, static, web site for yourself at  
  • A free, static, web site for your project at
    • You get one site per repo that is part of you repo, either in the docs directory or as a separate branch, gh-pages.
  • Easy -  That is if you like to use some flavor of markdown to edit text files instead of dealing with HTML. You aren't restricted to plain text, or just markdown, you can stick html or other into you repo.
  • A templated site with prebuilt templates for a consistent look and feel. GitHub use Jekyll, a static web site generation tool, to turn your text files and the template you select into a web site.  Jekyll runs on on GitHub's servers to build your site after you commit changes.
  • A site with no setup and no tools required - You can do everything from the web interface.  Nothing else is required.  Of course, you can still work on your local machine with your choice of tools, since your web site is just another git repo, or part of your existing git repo.
  • A "development environment" for your site, also no setup required.  Your site is a just a git repo hosted on github with all the things that come with it, revision control, rollbacks, change tracking, issue tracking, etc.

GitHub Pages - What they aren't:

  • A full web hosting account where you can run code to dynamically create pages, host a database, have email accounts, etc.
  • A tool to be used by someone that isn't comfortable with the basic concepts of:
    • source code control
    • markdown
    • what happens at "build time" vs. "run time".
  •  likely to get broken into - your pages are a static site generated at "build time", so there is very little "attack surface" to be exploited. 

 What can I do with a static site?

 This is something you either wrap your mind around or you don't.  There is plenty you can do with a static site that doesn't run any code. There is also plenty you can't do with it.   If you want WordPress, or a CMS, or some other app, get a web hosting account, try AWS, OpenShift, Google Compute Platform etc.   However I've seen a lot of "dynamic" sites that didn't need to be dynamic.

There is quite a bit that you can do at site build time.  There is also quite a bit that can be done but having processes that generate content that goes into your repo for displaying on your static site.

No comments: