Github pages

1. Make a Github web site using project pages

Sign up with github and make a new project
make a new branch called "gh-pages" (click on branch and enter name, click create)
click the '+' and make a page called index.html and enter some text, commit it
test the site at http://username.github.io/project-name/

2. Get Jekyll

Github doesn't support php client files, for web security reasons - so that means you can't use php includes in your pages (a standard means to insert a navbar or banner site-wide). So how do you include header, navigation bar or footer in plain html on every page and also be able to change them site-wide later on?

This is jekyll's work - you use "fluid includes" in your site build pages, jekyll reads them, and inserts what you specified in them for each page, thus producing all pages in plain html. There's no need for php includes. Then you just need to commit the built site to Github.

The jekyll website is certainly colourful, but it didn't help me understand what its really about, so here's how to use it...

Install jekyll with ruby
You will need to have a java environment installed too (openjdk isn't suitable either, the list of runtimes are here https://github.com/rails/execjs)

To create your website build, make a dir, cd there and run and browse http://localhost:4000 to see what the site (which is only a default index page so far) looks like

When you are working on the website and you want to view it as you make changes to pages, you need to make jekyll watch your build, and it will rebuild the site with every file save. But before we do that, let's see how we build...

3. Using Jekyll to build a pure html site

Important components..

Component	Location	Function
include	_includes	will be called by the web page - can be the header with css files, footer section, navigation bar, banner, whatever you need included on pages that you can make changes to later on and it will affect the whole site -saves editing every single html file
layout	_layouts	decides what includes to insert and in what order to fit them on a page
site page in html	top level or a sub-dir of build	calls a layout - so the layout then determines what includes to insert on the page

The necessary include files...

header.html
===========
Note: I added the "id" include to the <body> tag, so that I can set the body id on each html page as I like - see the page field setter below The class "ban" div sets the banner image using css, e.g. background-image: url(...); width: 100%; height: ...px; background-size: cover;

footer.html
===========

navbar.html
=========== Note: the navbar will be included on each page, so the links have to point to the top level, with `/`.
Also, the <nav> and </nav> tags are necessary for the css to be applied!
I added "id" to each link so that the buttons can be highlighted by the corresponding body id using css.

The layout file..

default.html
============

Web page html files..

something like this is placed at the top, to call layout, and set certain fields in the head and on the page:
Note: keywords are deprecated - search engine robots ignore them because of abuse, such as inserting false words for better search ranking.

These three important elements are in unique div sections, i.e. navbar, banner and content..

<div class="nav"> </div> wraps the lines in navbar.html

<div class="ban"> </div> wraps the banner in header.html

and content on each page is wrapped in another marker, i.e.

<div class="cont"> </div>

Just so that the navbar can sit right across the page width (100%), but the content have margins and padding that won't effect the navbar, and also the banner image stay behind the navbar - possible because different styles will be applied to each div element, as determined by its "class" - or "id".

You can use the z-index tag in the style for any div class, to determine which div element will be on top when other elements are displayed in the same region. e.g. a drop-down menu button that needs to be seen over a banner image, not hidden under it.

The z-index, e.g. "z-index: 10;", simply uses a number and the highest number has priority - this is html5.

You can make a template so that its easy to make new pages - I use bluefish html editor

4. Set the site's base URL

Github uses the user url as the root directory, not the project name, hence if your links are "/css/main.css" then Github will serve the css file to "http://user.github.io/css/main.css," which is not helpful, because they are pushed to http://user.github.io/project-pages/css/main.css.

So the site won't work at all.

Solution

set base url in the jekyll _config.yml file http://jekyllrb.com/docs/configuration/

then insert {{site.baseurl}}/ before all your internal links - possibly only navbar and sub-pages' links.. certainly any link that a sub-page will see

and in the header, e.g. {{site.baseurl}}/css/styles.css etc - I use bluetish's powerful search-replace tool to make a fast work, using my navbar.html page to get all the links

top-level pages can just remove the "/" before the url so that they point relative to pages on same or a level down, and not to root github.

images: change href="../ ---> href="{{ssite.baseurl}}/

and also src="../ ---> src="{{ssite.baseurl}}/

Also, links in css files, such as, "background-image: url({{ssite.baseurl}}/zimages/banner1.gif);"

5. Serving up with Jekyll..

to let jekyll do its work and convert your site files into real html, and serve it up to localhost for testing, you run this in your site dir:
or, if you are setting the base url, you need to serve the site at that url
The resulting html files are inside the _site dir - but these are purely for serving to localhost, because you upload from the build directory to Github and Jekyll does its work at there too.

Then preview the site (index.html) by browsing localhost:4000

because of the --watch option, jekyll will rebuild the site every time a file is saved, and all you need to do is hit refresh in the browser and your changes will be seen.

6. Commit files to Github

Firstly, setup your git user config..
Normally, you'd create a dir to clone your git repo into, cd there and run or, without cloning, run
..pushing-from-local-repository-to-github-hosted-remote

then switch to gh-pages (because the website will be served from the gh-pages branch)

Or, what you can do, if its purely a website you are aiming to host on Github and you don't have other branches, you can make gh-pages the master branch, and then remove "master" - via Github online (Settings > Branches > Default branch). After that you will not need the "checkout --orphan" command to reach gh-pages.

Stage your files with,
note: you can add by file names too, also, `git add .' adds files only in this path, whereas `git add -A' adds from all paths in local repo. `git add -u' adds only updated, not new files.

Then prepare your pages/files (commit) to the next Git push (upload) with
the -m option submits the reason for the commit to git.

Note: if you don't stage new files (add to tracking), you will get this kind of message: "nothing added to commit but untracked files present" with a list of local files that can't be commited becuse they are not tracked by Git yet.

to push all the new files or updated ones to Github, first make sure you have a personal authentication token from the Github site -> Settings > Developer > Personal Access Tokens, and check Repo and generate, and copy it.

then add to the file .git/config like this https://@github.com//.git

Then you can push changes to remote..
if you don't edit the .git/config file as above, you'll be promted for username and password (and you must enter the auth token - middle mouse press)

though, if you set gh-pages as the default branch, you may get this error: "fatal: The current branch gh-pages has no upstream branch", and you'll need to run,

If however you didn't clone the repo to local, and there are files on Github repo you don't have locally, you will get an error, "error: failed to push some refs to 'https://github.com/...' hint: Updates were rejected because the remote contains work that you do not have locally."

so you can use `git push origin master' or `git push -f' to force overwrite of files

to update your local repository to the newest commit, in case there are commits from elsewhere, execute

You can check status of your local clone with

check commit history with

To enable Git to store your username/pw (15min default) run

Fix a problem with having untracked files..

If status reports that your local and remote repo have diverged, you can run either of these two commands:
(where 'origin/gh-pages' is normally 'origin/master')
See the answer here stackoverflow.com...

Or if git status reports that your local repo is ahead by how many commits, and the online repo does not update, try reset with this command..
But the command will pull files from remote and overwrite on local, so backup local first!

Github tips https://gist.github.com/aguilarcarlos/dc8ff22845991c860e67

Git help https://help.github.com/

Ranger tips..

see my ranger key mapping for Jekyll/Git
add this line to the top section ot ranger's rc.conf, to show the Git status ot files in the margin (up-to-date or new version) for only your Git repo directory..

7. Testing and indexing

run your site through http://validator.w3.org/ which will show you what you need to fix (and check "Check linked documents recursively") - best if you bookmark that site and check your links (which often go down or 404) regularly
you can index your site at Google webmasters tools - you'll need to add tracking, like a tracking file or analytics key in the site header, which you get from G Analytics Admin > Accounts > New Account
and submit a site map which you can make with xml-sitemaps.com
or submit your site url at Bing - er, M$.. which Yahoo and Duckduckgo scan from
license your work at https://creativecommons.org/choose/

Home | Content | Site Map | TOP