Setup GitHub pages
Contents - Introduction - Setup GitHub - Create a Repository - Create a branch - Your first GitHub web pages - Markdown and layout using Atom - Replace index.html with index.md - Create Jekyll configuration - Commit and push your changes - Linking a Cascaded Style Sheet (CSS) - Resources
Introduction
In my previous blog I set up Jekyll and Atom for creating my first blog. To do so I used the Jekyll default theme (minima). But I wanted to have a better understanding of how Jekyll tags and commands work, and to publish my blog on GitHub.com. This blog is thus created without any template and only contain a very simple, single blog post written in markdown index.md in the blog (repository) root directory.
GitHub.com is a web based version control repository service. It is primarily used for program code, but can be used for any document tracking, and for publishing web pages. To keep track of different versions and edits of documents (codes, projects etc), GitHub stores different versions and edits in branches. By default, each repository contains a branch called ‘master’ where the latest operational version of your project is hosted.
To use GitHub for publishing web-pages, all you have to do is to create a special, stand alone, branch with the pre-defined name ‘gh-pages’. GitHub will take files found in ‘gh-pages’ and convert them into static html pages. You can publish simple text files or ordinary html coded files via the ‘gh-pages’. But the real strength comes with using markdown (or md) coded files, that are converted by GitHub to html coded files. Markdown files are much easier to work with compared to html coded files, and can yet be used for creating advanced web pages.
GitHub provides a special application, Jekyll for creating web pages using markdown. This blog will go through setting up GitHub, publishing a static html file, and creating and publishing markdown files using Jekyll. How to install Jekyll and the text editor Atom (for writing markdown file), is the topic of the previous blog.
My next blog covers using a more rich template Theme for Jekyll.
If you want to download the complete Jekyll setup for this blog it is available as a GitHub repository.
Setup GitHub
This blog uses the GitHub desktop.app for setting up a GitHub.com account, and managing and publishing GitHub pages. Alternatively it is also possible to set up your account directly on GitHub.com, and use the Terminal for managing and publishing.
Download and Install GitHub desktop.app.
Start GitHub desktop.app and create your own GitHub user account on GitHub.com from the GitHub desktop.app. When your account is created, log in to it; you can access it either from the GitHub desktop.app, or log in by going to GitHub.com in your web browser.
Create a Repository
You can create a repository either from the GitHub desktop.app or directly in GithUb.com. In the first case you need to publish the repository to GitHub.com, in the latter you have to clone the online repository to your local computer. In both cases you will end up having two clones of your repository, one online (at GitHub.com) and one on you local computer. This blog describes how to create the repository using the GitHub desktop.app.
In the GitHub desktop.app go via the menu:
Enter a name (‘setup-github’) and a description. To create a new repository you have to enter a Local Path in the text box, if you create the path using the button, GitHub desktop.app will treat it as an existing local repository to Add (rather than Create). You can leave Git Ignore and License to None. Click .
In the top menu, you now have to click Publish repository. In the window that opens, un-check Keep this code private, and click . By default the Branch tab in the top menu will say ‘master’.
If you check your online GitHub.com account, your new repository should appear after a few minutes. You need to refresh your web pages to see it
Create a branch
In order to publish your own web-pages on GitHub, you have to create a special branch called ‘gh-pages’.
Open GitHub desktop.app, In the top menu you should see three alternatives:
Current Repository : Current Branch : Fetch original
To create a new branch click on the little expansion triangle to the right of the text Current Branch. In the drop down menu that appears, click , and enter ‘gh-pages’ (without quotation) in the Name text box, and click . The Current Branch should now indicate that ‘gh-pages’ is your current branch. For GitHub to put the new branch to your online repository at GitHub.com, you must also click the new Publish Branch tab in the top menu of GitHub desktop.app.
Once you have published a branch, the Publish Branch tab will be replaced by a tab that instead says either Fetch origin or Push origin. Every time you commit a change, the tab will change to Push origin, and you must click it in order for GitHub to push the committed changes to your online GitHub.com branch (as indicated in the Branch tag).
Your first GitHub web pages
At this stage you must create a very simple file called index.html, and put it in the local copy (clone) of your GitHub repository. If you do not have a suitable text editor, use the previous blog to download and install Atom. The file (index.html) should only contain text (no html code). For example:
My first GitHub page.
Return to the GitHub desktop.app, where you should now see index.html in the list under the Changes tab (in the row below the top menu). Before you can commit the Changes, you must write a Summary (and better also a Description). Once you have entered a summary, the button at the bottom will clear (if the button does say ‘master’ instead of ‘gh-pages’, you must change, or create, the branch ‘gh-pages’ as described in the previous section). Click to commit your changes.
The list in the Changes tab should clear. To push the committed files to the repository, you must also Click Push origin in the top menu.
It will take up to 10 minutes for GitHub to receive and publish the changes. Go to your account in GitHub.com (use your web browser) and navigate to the repository (in my case ‘setup-github’) you are working with. Find the button, and click it to change to the ‘gh-pages’ branch. The file index.html should appear. If not, refresh the page, and make sure you did click Push origin in the top menu of the GitHub Desktop.app.
When the file index.html appears under the branch ‘gh-pages’ in your GitHub.com account, you can view your page under the url address:
http://'yourGitHubUser'.github.io/'repository'
where ‘yourGitHubUser’ is the name of the GitHub account you created, and ‘repository’ is name of the repository (‘setup-github’ in my case) that you first cloned and then added the file (index.html) to. The web page will be a single paragraph, regardless the length of your text.
When you make any changes to your local clone of index.html (or any other file in the local clone folder of your GitHub repository), the changed or added files will appear under the Changes tab in the GitHub desktop.app, and you have to repeat commit and push origin in order to transfer the files to your GitHub.com online repository.
Markdown and layout using Atom
You can use any text editor to follow the rest of this blog, but the detailed commands are written for Atom. How to install and set up Atom is described in the previous blog.
Start Atom, and go via the main menu:
The New Window will open with some default tabs, including the Welcome Guide. Click it and select ‘Open a Project’, and then click the button that also says Open a project. Navigate to the folder containing the local clone of your GitHub repository, and select the folder to be your Project.
In the Atom Project pane that opens you should see the index.html file that you created above. You are going to change the file from html to markdown, and add some markdown codes.
Replace index.html with index.md
To rename index.html to index.md, select it in the Atom Project pane and ctrl-click (or left click) on your track pad or mouse; in the list that appears, select and change the extension from .html to .md.
Open index.md in Atom by just clicking on it in the Project pane. Replace the content of index.md with the following:
---
layout: default
title: Setup GitHub pages
date: '2017-12-25 11:56'
---
## My first heading
[Other web page](url) is my _favorite_ site for ...
The code embraced by the triple hyphens (—) defines the front matter, and is called YAML as the jargon goes. YAML can contain a lot more, but we will just set layout, title and date. You should keep the YAML exactly as it is. ## is the markdown code for <h2> (header level 2), the markdown code []() is for linking a url, and the underscore (_) enclosure is the markdown code for italic fonts.
Save the edits by going via the Atom main menu:
To add layout, and header and footer to your web page you first need to add two subfolders in your repository. You can use Atom in a similar manner as when you renamed the file above. Select the project top folder (‘setup-github’) and ctrl-click, in the list that appears select . Create a folder named _layouts. Repeat and create another folder named _includes.
Create a new file using Atom, go via the main menu:
An empty file opens. Copy and paste the following code to the empty file:
{% include header.html %}
<h1>{{ page.title }}</h1>
{{ content }}
{% include footer.html %}
And save it in the _layouts folder as default.html:
To understand the code a bit, a quick explanation is required:
The include tag
{% include header.html %}
looks for a file in the _includes folder with the indicated name (footer.html) and inserts it in place of the include tag itself.
The double curly braces are instead replaced by the text that is referred to. In the file default.html above, the tag
{{ content }}
is replaced by the content of index.md, following the YAML code, and the tag
{{ page.title }}
is replaced by the YAML title given in index.md.
The files header.html and footer.html referred to in default.html do not exist. You need to create them and put them in the subfolder _includes. header.html should contain the following text:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Setup GitHub pages</title>
<link rel="stylesheet" href=" css/styles.css" >
</head>
<body>
And footer.html should contain this text:
</body>
</html>
Create Jekyll configuration
Finally you have to create the Jekyll configuration file _config.yml, directly under the Project (or repository) folder (in my case setup-github). Copy and paste the following content to it:
name: My first GitHub page
markdown: kramdown
rouge: true
baseurl: ""
Commit and push your changes
Return to GitHub desktop.app, all the files you have created should be listed under the Changes tab. Enter a Summary and a Description, and click the button (details above). Then click the top menu tab Push origin that appears after you committed the files.
Open your web browser and return to your online GitHub.com account. Wait for the files to appear in the ‘gh-pages’ branch. When they appear, you can open (or refresh) your own web page:
http://'yourGitHubUser'.github.io/'repository'
Linking a Cascaded Style Sheet (CSS)
So far the web page does not contain any style (CSS), even if the header.html has a link to a CSS file.
<link rel="stylesheet" href=" css/styles.css" >
For this web page I copied the style sheet that was created in the previous blog, and saved it as /css/styles.css under my repository root folder. I then also copied the top banner with the text ‘Geo Imagine Developer’ and the About link. And then I did the same thing for page trailing content.
I finally used the package markdown-toc to generate the table of contents. And then I commited and pushed my local repository to my GitHub.com account.
Cleanig up repository
When I committed and pushed the repository I discovered that it contained an internal macOS file (.DS_Store) and redundant folder (_drafts) and _site). To remove them from the repository I first created a .gitignore using the Terminal:
$ touch .gitignore
Despite being a hidden file (starting with a dot[.]) it can be seen and edited in Atom, and you have to enter the files and folders that git should ignore.
.DS_Store
_site/
_drafts/
The _site) folder is recreated each time you start Jekyll, and it will also the created automatically from the ‘gh-pages’ branch at GitHub.com, and published as a web-site (you will not see them inside your repository though).
In the Atom Project pan, the files and folders in .gitignore will change color, indicating that they are ignored by git.
As the file and the folder were already in the GitHub.com repository, I had to remove them ‘manually’ from git using the Terminal:
git rm –cached _drafts/’filename’
and
git rm –cached .DS_Store
I then actually had to make an edit to one of the other files in the repository in order for GitHub desktop to understand that I wanted to commit and push the changes. Then I got rid of the unwanted files and folders in the online repository.
If you want to see the files used for building this blog, the completed repository is available on GitHub.com.
Resources
Get Started With GitHub Pages by Anna Debenham
How to Upload Jekyll to Github Page by Thoriq Firdaus
This blog repository on GitHub.com
Setup blog tools: Jekyll and Atom my previous blog
Setup Jekyll Theme blog my next blog