Software Development

Explore GitHub Pages, a web developer's playground

GitHub provides a vehicle for hosting and sharing your Git-based code and resources. Here's how to use the feature called GitHub Pages.

githuboctocatlogo043014.jpg
 Image: GitHub

Setting up an online presence has never been simpler, as there are hosting options with a variety of cloud platforms as well as free options. The service to use depends on requirements, costs, and so forth.

GitHub provides one option for static sites that includes the power of Git and GitHub, thus the perfect solution for developers. Learn what GitHub Pages offers, and how you can get this feature up and running in no time.

Store and serve your code

You store files, usually code, on GitHub. These files can include web content (HTML, JavaScript, CSS, etc.), and this content can be served via the GitHub Pages feature. The added bonus is the site's resources are source controlled with all the power of Git via GitHub.

GitHub Pages can be implemented a few ways. You can have one site for the complete repository, along with individual sites for each project. Let's begin with creating a site for user repository.

Create a site for repository

A GitHub repository may have one site called a user site; the syntax for it is [username].github.io. My repository is under my username aspatton, so my GitHub user site is aspatton.github.io. This is set up by creating a new public repository with the [username].github.io (Figure A). Once the new repository is created, the screen in Figure B is presented. The GitHub Pages feature is accessed via repository settings -- click Settings (lower right in Figure B) to access the page shown in Figure C.

The GitHub Pages section of repository settings is visible in Figure C -- it includes a page generator to quickly get your site up and running. You can choose to create your own pages, but the automatic page generator (button shown in Figure C) is a nice feature. Once it is selected, the create page displayed in Figure D is presented. You can edit the page name (shown in the banner at the top of the page) along with the tagline and body of the HTML page.

Figure A

githubpagesfiga0512014.jpg

Creating a repository for the GitHub Pages feature

Figure B

githubpagesfigb0512014.jpg

A new GitHub Pages repository is created.

Figure C

githubpagesfigc0512014.jpg

The GitHub Pages feature is available via repository Settings.

Figure D

githubpagesfigd0512014.jpg

The Create GitHub User Pages site page

The final part of automatic site creation is layout selection -- click the Continue To Layouts button, which you see at the bottom of Figure D. Figure E shows the layout options across the top; select one of the options, and the site is created. Figure F shows the newly created GitHub User Pages repository opened via the standard GitHub interface. Figure G shows the site opened in Chrome.

Once the site is created, you may choose to edit the site or add pages/files via the GitHub interface or your favorite set of tools. GitHub does provide an online editor, so it can be used to edit files like HTML. Figure H shows the index.html file viewed via the GitHub site with the many edit options available as buttons -- the Edit button takes you to the online editor shown in Figure H. If you would rather edit locally, a local clone can be created where you make the changes and push the changes to the GitHub repository when ready. This can be accomplished via the command line or using the GitHub client.

Figure E

githubpagesfige0512014.jpg

Layout options for the newly created GitHub User Pages site.

Figure F

githubpagesfigf0512014.jpg

The newly created GitHub Pages repository.

Figure G

githubpagesfigg0512014.jpg

Viewing the GitHub User Pages site in Chrome.

Figure H

githubpagesfigh0512014.jpg

Viewing the file via GitHub with various edit options (buttons).

Figure I

githubpagesfigi0512014.jpg

Editing the site page via the GitHub online editor.

Project sites

While GitHub Pages only allows one user site, you can create multiple sites under it for each of your projects. Creating a site for a project repository can be accomplished a number of ways.

The simplest approach is what has been covered so far. You create a new repository or access an existing repository and go to its settings and work with the GitHub Pages section (Figure C). The end result is the GitHub Pages files (Figure F) within the project repository. Project repositories that use GitHub Pages will use the special gh-pages fork instead of the master fork used for the main repository.

Another option for creating a site for a GitHub project repository is manually creating a new fork called gh-pages, adding any necessary resources, and pushing the changes to the GitHub project repository. Also, you should go to the project repository settings and set the Default branch to the newly created gh-pages branch (this option is visible at the top of Figure C). The GitHub Pages site for projects works the same as the main user site, so you can add and edit resources as necessary. The project site is accessible as a directory under the main site, so a project called TechRepublic under my main site is accessed via the following URL: aspatton.github.io/TechRepublic.

A great option for developers

I stumbled upon the GitHub Pages feature while working with the many other features of Git and GitHub. It's a great resource for creating sites for your GitHub projects, and it provides an excellent free resource for building and playing with code in a static website.

The basic features of GitHub Pages just scratches the surface, as there are many options and much more to learn. One caveat with GitHub Pages is its static nature, but you can use other tools like Jekyll to extend it. Also, you may want to learn more about GitHub Flavored Markdown (GFM), as it is included in generated pages and is used throughout GitHub.

Have you used GitHub Pages? If so, how did you use it, and what did you think of the feature? Post your feedback in the discussion.

About

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...

2 comments

Editor's Picks