(A very good place to start). This inaugural post outlines how I’ve set up this GitHub page and explains the basic features I’m using. I’ll describe the features then give examples and links to how it’s done on this GitHug page. This should serve as simple primer for setting up a GitHub page.

Let’s start with this GitHub page. In addition to its Git repository hosting service, it can also host a web page as a GitHub page. It seems to be a common tool for people sharing their code, and seems both convenient and powerful. I’ve only been using it the last day or two to set up

Websites served through GitHub are powered by Jekyll, a static site generator. It takes a bunch of text files, runs it through a converter like Markdown and their Liquid renderer, generating the actual HTML that gets served to the client. More info is available at Jekyll’s docs.

I’ve been using what are probably the most basic features. They are:

1. Templates. Say I have a main page, an "about me"page, and pages that display blog posts. Those pages all have similar information that should look the same (a title, a navigation bar, a link to something). So Jekyll lets you make a template that has all that marked up: the title should look like this and go there, the navigation bar should have these links, etc. Essentially, it acts as a wrapper for whatever pages uses this template. The main, "about me," and blog pages will all refer back to the template to see how those things should look. This way, there's no need to copy it into each blog, or worse, decide to update how they should look and have to change it on every, single blog post you've ever written.

   For example, let's say you've made a template for blog posts. It says to put the the title (whatever that might be) at the top, put the blog text in the middle, then a link to your webpage at the bottom.

   Now you want to make a blog post about beanies using this template. You do so by writing a Markdown text that says to use the blog post template and provide the information that the title is "Beanies are great!" and the content of the blog is "Hey, I had this thought the other day..." Jekyll will read the template and follow its instructions to put the title, "Beanies are great!" at the top of the page, and put the contents of the blog in the middle, then put a link to your blog at the bottom.

   Note that Jekyll has special directories and files which serve specific functions. For example, a _layout directory contains templates that wrap posts and the _posts directory will hold the Markdown text that will have the contents of your blog posts.

2. Scripting abilities. Once you have made some templates, Jekyll can run script functions (such as if/else and for loops) and use variables that can retrieve information from other files. Jekyll uses the Liquid templating language to do so.

   In the templates described above, variables were passed between text files, spcifically between the template and the blog post. The blog post named its title as "Beanies are great!" and the template pulled that variable to use as the title when generating a web page for that post. This is a list of site variables in Jekyll.

   Jekyll can also run simple functions such as if/else statements and for loops. For example, suppose you have a bunch of blog posts. You could do a for loop over all blog posts and display the blog posts which contain the word "Hello" in them or were posted betwen June and July.

3. Tags using Liquid. Jekyll doesn't seem to have native support for tags. Tags were incorporated by using the underlying Liquid templating language using these very helpful instructions.

So let's write out specific examples of how this GitHub page got set up. These instructions will assume you are using GitHub's website interface but should be general enough otherwise (e.g. using Git).

1. Set up a GitHub page. Create a new repository on your GitHub account with the name username.github.io where username is your GitHub username.

2. Create a layout template. Create a directory named _layout and create a file named default.html. Directories can be created on GitHub's website by creating a new file and adding a forward slash (/), i.e., create a new file named _layout/default.html.

   In default.html, create a layout for how web pages using this default template will display information. The template HTML will have include static information that will show up the same on all pages, such as a navigation bar. The template HTML will also have dynamic information such as a page title. This will have to be pulled from the page you're making, for example, the title of the page or its main content.

   The dynamic information is accessed using Liquid by referring to certain variables. For example, the title of the web page is referred to as {{ page.title }} . Then you could make a simple template like the following:

   <!DOCTYPE html>
     <html>
   	
       <head>
         <title>{{ page.title }}</title>
         <link rel="stylesheet" type="text/css" href="/css/main.css">
       </head>
   	
       <body>
   
         <nav>
           <ul>
           <li><a href="/">Home</a></li>
           <li><a href="/about">About</a></li>
           <li><a href="/blog">Blog (by date)</a></li>
           <li><a href="/tags">Blog (by tag)</a></li>
           </ul>
         </nav>
   
         <div class="container">
           {{ content }}
         </div><!-- /.container -->
   
       </body>
     
     </html>

   Note that the {{page.title}} and {{content}} will pull that information from the page, such as "Welcome" and "Hello World!"

3. Create pages using templates.

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html