Host HMTL Code on the Web with GitHub Pages

By Jack Dougherty, last updated May 5, 2015

If your digital project includes HTML code (or JavaScript, CSS, etc.) that needs to be hosted on a live website, one solution is to upload your work to a free GitHub account and publish to the open web using its GitHub Pages feature. Hosting your code is free is you make it public, while private code requires a monthly payment. The GitHub platform is widely used by the open-source coding community to share and collaborate on digital projects, because other users can easily view your work, make a copy, and even suggest improvements. GitHub Pages works well for demonstrating work on a live public website, but if your project involves private data or draws high-volume web traffic, you should host your code on a secure dedicated web server.

Newcomers can host their code on GitHub, and publish to the web using the GitHub Pages feature, by following step-by-step instructions or this YouTube video screencast.

This basic tutorial demonstrates how to work with GitHub entirely through the browser. More advanced GitHub users may download other free tools (such as GitHub for Mac or GitHub for Windows) or use other methods (such as the terminal command line) to work more efficiently.

1) Inside your free GitHub account, create a new repository (also known as a repo) to host your project's code (such as an index.html file and more).

GitHub-NewRepo

2) Enter a repository name and description and check the box to automatically add a README file. If desired, select an open-source license (such as MIT), and click the Create Repository button.

GitHub-CreateRepo

3) Your new repository automatically starts opens the "master" branch. Use the drop-down menu to create a new branch, and name it "gh-pages" (which is short for GitHub Pages), and press enter or return on your keyboard.

GitHub-CreateBranch

In this tutorial, we do all of our editing and testing work in the gh-pages branch, which automatically appears on the public web. When we're done, we will pull a copy (or sync) our completed work to the master branch for safekeeping and open sharing.

4) To add ONE NEW FILE to the gh-pages branch, click the + button next to the repository name and enter the file name. For example, index.html is the default file name for most web projects.

GitHub-CreateNewFile5) Select the "soft wrap" option (which makes long code strings more readable), and paste code into the editor. In this example, I pasted HTML code that was generated by publishing an interactive chart from a Google Spreadsheet.

GitHub-CreateFile

6) At the bottom, select the "commit" button (which means you are making a code change). Optionally, name and describe your commit, if you wish to track changes to your work.

GitHub-CommitButton

7) Edit an existing file in the gh-pages branch by selecting its title. For example, select the README filename (which should have been automatically generated when you created the repository and the gh-pages branch). On the next screen, select the Edit button.

GitHub-EditFile

GitHub-EditFile2

8) When editing the README file, type a link to the live web version of this repository, so that visitors may easily click to view it. The GitHub generic public web address is a combination of your username and ".github.io/" and your repository name, like this: http://USERNAME.github.io/REPOSITORYNAME

In my README file, I typically write it this way so that visitors know to click the link: View live demonstration site at http://JackDougherty.github.io/demo

Commit your change to the README file in the gh-pages branch by pressing the green button at the bottom of the editor page.

GitHub-EditReadMe

Hint: If you named your file "index.html" then you don't need to add anything else to the web address, because the site will automatically point to this default file. But if you entered a different file name, such as "sample.html", then you need to add it to the web address in this way: http://Username.github.io/Repositoryname/sample.html

9) Select the repository name to go to the upper-most file in the gh-pages branch.

10) To view your live index.html code on the public web, click the link you created in your README file. (Hint: use the right-click feature to open in a new tab/window). Important: The very first time you create a gh-pages branch, it may take up to 10 minutes for its content to appear on the open web. Afterwards, when you add or edit files in this branch, they should appear nearly instantly on the web, though you may need to refresh your browser to view any changes you have made.

GitHub-SelectRepoName2

11) To add MULTIPLE FILES to the gh-pages branch, you could copy and paste each one individually as shown above, or choose one of these labor-saving options:

GitHub-ForkCloneDownloadIf a code template already exists somewhere on GitHub, "fork" a copy of the repository to your own account, create a gh-pages branch for the live web, and edit/modify the files as desired. To sync and upload multiple files from your desktop to a GitHub repository, use the free GitHub for Mac or GitHub for Windows tool, which features a graphical user interface to do tasks above very easily. Advanced coders may use command-line instructions to upload and sync files to GitHub most efficiently. 12) To BACKUP and SHARE your work: After adding or editing files in the gh-pages branch, create a "pull request" (to merge files) to the master branch.

GitHub-PullRequest

13) Use the drop-down menus to CAREFULLY select the direction of the merge in this TO-FROM format: TO master branch FROM gh-pages branch

GitHub-ToFrom

14) Follow these steps to finish the pull request, which merges all content TO the master branch FROM gh-pages branch:

Create the pull request (select green button) Give it a title (such as "updated index and ReadMe") Send pull request (green button) Merge pull request (another green button) Confirm merge (and another green button!) Always double-check your repository branch names to do editing and live web testing in the gh-pages branch, then make sync a copy to public share in the master branch.

To embed an interactive data visualization from a GitHub Pages host site into a secondary website (such as an organization's WordPress.org site), see the Embed iframe with WordPress tutorial (TO COME).

See my sample repositories, with links to live demo sites, at https://github.com/JackDougherty?tab=repositories. Learn more about GitHub general features to share and collaborate on other users' public code repositories.

Creative Commons License
Data Visualization for All by Jack Dougherty and contributors is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. You may freely share and modify this content for non-commercial purposes, with a source credit to the author(s) listed in the byline and this link: http://DataVizBook.org.