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)
You might also need to run this, to fix the issue that gems are not found. Using bundler ensures Jekyll uses the gems specified in your Gemfile and Gemfile.lock.
Actually, it is recommended to install gems into a user-specific dir, so that they are easily found.
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, e.g. using bluefish html editor
To enable markdown in your files, a kind of short-hand that jekyll translates into full html, such as blank lines, bold text, web links, images, tables (check the cheat sheet available), make sure files are given the .md erxtension. You still need to link to them as .html files though as Jekyll creates them as html.
And a tip to enable markdown inside 'div's: add this inside the div tag: markdown="1"
However, I still could not achieve paragragh spaces. So I needed to use 'commonmark' instead of 'kramdorn'. Use this by adding this line to your Gemfile, under the plugins group:
and these lines in your _config.yml file:
and then update jekyll with this..
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.
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.
Also, links in css files, such as, "background-image: url({{site.baseurl}}/zimages/banner1.gif);"
Note that if you publish the site through Cloudflare (see below) you won't need to do this, and if your site is already set up for github pages you'll need to remove all the {{site.baseurl}} tags.
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
or use this if you have installed gems with bundler (bundle install)
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/project-name
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
(For a private repo, do this instead)
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://<personal-access-token>@github.com/<username>/<repository>.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!
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
I recommend that once you've pushed your site you do some rigorous testing - before you go off on a holiday and leave a ton of page link errors or 404's to external sites which you didn't know about..
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
Gitlab works in almost the same way as github (pushing using git is identical) and it's also still run by opensource people (not like github, now owned by a sufer large company).
Once you sign up and create a repo, there is immediate instructions on how to clone the repo.
It is possible to run a website from gitlab (differs to github) but instead you can sign up with cloudflare and run unlimited free websites from there, easily linking any gitlab or github repo - and no one can tell where your files are actually hosted.
Gitlab actually runs all the page builders you can imagine, including jekyll, but it also has to install all the correct plugins that you require and this can cause it to fail to built the site.
Therefore, the easiest method is to build your site locally and push the built site files (post jekyll etc.) to your repo. Then with cloudflare leave the build hooks empty and deploy the site directly.
To build your site locally, you just use the -d switch with the `jekyll build` command and supply the location, and to make it build in a adjacent folder you can use ../
like with this example..
But first, create the build dir, e.g. site/SITENAME-build, and clone the repo into that dir. This will create the git config files and version control so that you can commit/push to the repo.
Thereafter, all your work goes on in your main site dir, e.g. site/SITENAME, and you only enter site/SITENAME-build dir to run git add, commit and push etc. You shouldn't edit files there, as they are wiped with every new build, and they might look a complex mess of html anyway after jekyll has built the files.
Whenever you need to push changes to the remote repo, you run the build command from your work dir, then switch to build dir and sun commit, push.
If you previously hosted a site with a github web address and move it to cloudflare, or buy a domain name, you should redirct web traffic that arrives there to the new address!
In your repo or previous repo, go to settings and you should find a redirect option, where you enter the new site address. This will keep your search engine listing intact too (better than a redirect script in your site header). You can also make sure there's a 404 page on the repo if it's not used any more.
And remember that cloudflare sell domain names for the best value aroiund ($13/yr) and ofer free SSL certification, though it will need adding to the domain afterward. Load times are extremely fast, and especially if you optimise the site with clean code and CSS, and format images to webp 15% etc.