February 1, 2016
github hosting
A Guide to Creating and Hosting a Personal Website on GitHub | Jonathan McGlone
Source
A step-by-step beginner’s guide to creating a personal website and blog using Jekyll and hosting it for free using GitHub Pages.
View Demo Site Download Demo Files
This guide is meant to help Git and GitHub beginners get up and running with GitHub Pages and Jekyll in an afternoon. It assumes you know very little about version control, Git, and GitHub. It is helpful if you know the basics of HTML and CSS since we’ll be working directly with these languages. We’ll also be using a little bit of Markdown, but by no means do you need to be an expert with any of these languages. The idea is to learn by doing, so the code we’ll be implementing in this tutorial is available in this guide or can be downloaded entirely at this GitHub repo. Feel free to copy and paste or type this code directly into your project’s files.
For a little background on why I chose GitHub and GitHub Pages for my personal website (and other projects), see this note.
Other Resources You Should Know
In order to make GitHub Pages accessible to a wider audience, this guide focuses on using the web interface on github.com to build your personal website, thereby generalizing and glossing over the standard tools associated with Git and GitHub. To get a lot dirtier wit Git and GitHub (ie, the command line and terminal), there are several other great guides you should also know about, probably bookmark, and read after completing this one, or jump over to if that is more your speed: Anna Debenham, Thinkful, and even GitHub itself go above and beyond making the command line or local workflow of GitHub hosting and Jekyll templates accessible to a wider audience.
Also, at the end of this document, there is a pretty good list of resources related to Git, GitHub/Pages, Jekyll, and Markdown that can help you dive deeper into these tools. I’ll do my best to keep this list updated as I find new ones.
What is Git, GitHub, and GitHub Pages?
Git, GitHub, and GitHub Pages are all very closely related. Imagine Git as the workflow to get things done and GitHub and GitHub Pages as places to store the work you finish. Projects that use Git are stored publicly in GitHub and GitHub Pages, so in a very generalized way, Git is what you do locally on your own computer and GitHub is the place where all this gets stored publicly on a server.
Git
Git is a version control system that tracks changes to files in a project over time. It typically records what the changes were (what was added? what was removed from the file?), who made the changes, notes and comments about the changes by the changer, and at what time the changes were made. It is primarily used for software development projects which are often collaborative, so in this sense, it is a tool to help enable and improve collaboration. However, its collaborative nature has led it to gain interest in the publishing community as a tool to help in both authoring and editorial workflows.
Git is for people who want to maintain multiple versions of their files in an efficient manner and travel back in time to visit different versions without juggling numerous files along with their confusing names stored at different locations. Think of Git and version control like a magic undo button.
In the diagram below, each stage represents a “save”. Without Git, you cannot go back to any of the in between stages from the initial draft and final draft. If you wanted to change the opening paragraph in the final draft, you’d have to delete data that you couldn’t recover. To work around this, we use the “save as” option, name it something different, delete the opening paragraph and start writing a new one.
With Git, the flow is multidirectional. Each change that is significant is marked as important in a version, and you proceed. If you you need to get back to earlier stages, you can without any loss of data. Presently, Google Docs “revision history” or Wikipedia’s “edit history” work in this sort of fashion. Git is just a lot more detailed and can get a lot more complex if needed.1
When you have the chance, I highly recommend this 15 minute, hands-on web tutorial on using Git.
GitHub
GitHub is a web hosting service for the source code of software and web development projects (or other text based projects) that use Git. In many cases, most of the code is publicly available, enabling developers to easily investigate, collaborate, download, use, improve, and remix that code. The container for the code of a specific project is called a repository.
There are thousands of really cool and exciting repositories on GitHub, with new ones added every day. Some examples of popular software development projects that make their code available on GitHub include:
- Twitter Bootstrap, an extremely popular front-end framework for mobile first websites, created by developers at Twitter.
- HTML5 Boilerplate, a front-end template for quickly building websites,
- The JavaScript Visualization Library D3
- Ruby on Rails, the open-source web framework built on Ruby.
Usually, people just host the files that contain their code, so what you see on the end view is the actual code, as in this example from the Ruby on Rails project:
GitHub Pages
GitHub Pages are public webpages hosted for free through GitHub. GitHub users can create and host both personal websites (one allowed per user) and websites related to specific GitHub projects. Pages lets you do the same things as GitHub, but if the repository is named a certain way and files inside it are HTML or Markdown, you can view the file like any other website. GitHub Pages is the self-aware version of GitHub. Pages also comes with a powerful static site generator called Jekyll, which we’ll learn more about later on.
Getting Started with GitHub Pages
Don’t worry if some of these concepts are still a little fuzzy to you. The best way to learn this stuff is to just start doing the work, so let’s not waste anymore time and dive right in.
1Create your project’s repository. Login to your GitHub account and go to https://github.com/new or click the New repository icon from your account homepage.
2 Name your repository username.github.io, replacing username with your GitHub username. Be sure it is public and go ahead and tell GitHub to create a README file upon generating the repo.
3 Create an index.html page by clicking the plus icon next to your repository name and typing the file name directly in the input box that appears.
On the resulting page, put this markup inside of the GitHub text editor:
<!DOCTYPE html>
<html>
<head>
<title>Hank Quinlan, Horrible Cop</title>
</head>
<body>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
<li><a href="/cv">CV</a></li>
<li><a href="/blog">Blog</a></li>
</ul>
</nav>
<div class="container">
<div class="blurb">
<h1>Hi there, I'm Hank Quinlan!</h1>
<p>I'm best known as the horrible cop from <em>A Touch of Evil</em> Don't trust me. <a href="/about">Read more about my life...</a></p>
</div><!-- /.blurb -->
</div><!-- /.container -->
<footer>
<ul>
<li><a href="mailto:hankquinlanhub@gmail.com">email</a></li>
<li><a href="https://github.com/hankquinlan">github.com/hankquinlan</a></li>
</ul>
</footer>
</body>
</html>
4 Commit index.html. At the bottom of the page, there is a text input area to add a description of your changes and a button to commit the file.
Congrats! You just built your first GitHub Pages site. View it at http://username.github.io. Usually the first time your GitHub Pages site is created it takes 5-10 minutes to go live, so while we wait for that to happen, let’s style your otherwise plain HTML site.
5 To style the content go back to your repository home and create a new file named css/main.css. The css/ before the filename will automatically create a subdirectory called css. Pretty neat.
Place the following inside main.css:
body {
margin: 60px auto;
width: 70%;
}
nav ul, footer ul {
font-family:'Helvetica', 'Arial', 'Sans-Serif';
padding: 0px;
list-style: none;
font-weight: bold;
}
nav ul li, footer ul li {
display: inline;
margin-right: 20px;
}
a {
text-decoration: none;
color: #999;
}
a:hover {
text-decoration: underline;
}
h1 {
font-size: 3em;
font-family:'Helvetica', 'Arial', 'Sans-Serif';
}
p {
font-size: 1.5em;
line-height: 1.4em;
color: #333;
}
footer {
border-top: 1px solid #d5d5d5;
font-size: .8em;
}
ul.posts {
margin: 20px auto 40px;
font-size: 1.5em;
}
ul.posts li {
list-style: none;
}
Don’t forget to commit the new CSS file!
6 Link to your CSS file inside your HTML document’s <head>. Go back to index.html and select the “Edit” button.
Add a link to main.css (new markup is in bold):
<!DOCTYPE html>
<html>
<head>
<title>Hank Quinlan, Horrible Cop</title>
**<!-- link to main stylesheet -->**
**<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="/cv">CV</a></li>
<li><a href="/blog">Blog</a></li>
</ul>
</nav>
<div class="container">
<div class="blurb">
<h1>Hi there, I'm Hank Quinlan!</h1>
<p>I'm best known as the horrible cop from <em>A Touch of Evil</em> Don't trust me. <a href="/about">Read more about my life...</a></p>
</div><!-- /.blurb -->
</div><!-- /.container -->
<footer>
<ul>
<li><a href="mailto:hankquinlanhub@gmail.com">email</a></li>
<li><a href="https://github.com/hankquinlan">github.com/hankquinlan</a></li>
</ul>
</footer>
</body>
</html>
Visit http://username.github.io to see your styled website. It should look at like http://hankquinlan.github.io.
Using Jekyll with GitHub Pages
Like GitHub Pages, Jekyll is self-aware, so if you add folders and files following specific naming conventions, when you commit to GitHub, Jekyll will magically build your website.
While I recommend setting up Jekyll on your own computer so you can edit and preview your site locally, and when ready, push those changes to your GitHub repo, we’re not going to do that. Instead, to quickly get a handle on how Jekyll works, we’re going to build it into our GitHub repo using the GitHub web interface.
What is Jekyll?
Jekyll is a very powerful static site generator. In some senses, it is a throwback to the days of static HTML before databases were used to store website content. For simple sites without complex architectures, like a personal website, this is a huge plus. When used alongside GitHub, Jekyll will automatically re-generate all the HTML pages for your website each time you commit a file.
Jekyll makes managing your website easier because it depends on templates. Templates (or layouts in Jekyll nomenclature) are your best friend when using a static site generator. Instead of repeating the same navigation markup on every page I create, which I’d have to edit on every page if I add, remove, or change the location of navigation item, I can create what Jekyll calls a layout that gets used on all my pages. In this tutorial, we’re going to create two Jekyll templates to help power your website.
Setting Up Jekyll on github.com
In order for Jekyll to work with your site, you need to follow Jekyll’s directory structure. To learn about this structure, we’re going to build it right into our GitHub repo.
7 Create a .gitignore file. This file tells Git to ignore the _site directory that Jekyll automatically generates each time you commit. Because this directory and all the files inside are written each time you commit, you do not want this directory under version control.
Add this simple line to the file:
_site/
8 Create a _config.yml file that tells Jekyll some basics about your project. In this example, we’re telling Jekyll the name of our site and what version of Markdown we’d like to use:
name: Hank Quinlan, Horrible Cop
markdown: kramdown
At this point, I’m hopeful that you’ve got the hang of creating files and directories using the GitHub web interface, so I’m going stop using screenshots to illustrate those actions.
9Make a _layouts directory, and create file inside it called default.html. (Remember, you can make directories while making new files. See the main.css step if you forgot.)
This is our main layout that will contain repeated elements like our <head> and <footer>. Now we won’t have to repeat that markup on every single page we create, making maintenance of our site much easier. So let’s move those elements from index.html into default.html to get something that looks like this in the end:
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }}</title>
<!-- link to main stylesheet -->
<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="/cv">CV</a></li>
<li><a href="/blog">Blog</a></li>
</ul>
</nav>
<div class="container">
{{ content }}
</div><!-- /.container -->
<footer>
<ul>
<li><a href="mailto:hankquinlanhub@gmail.com">email</a></li>
<li><a href="https://github.com/hankquinlan">github.com/hankquinlan</a></li>
</ul>
</footer>
</body>
</html>
Take note of the {{ page.title }} and {{ content }} tags in there. They’re what Jekyll calls liquid tags, and these are used to inject content into the final web page. More on this in a bit.
10 Now update your index.html to use your default layout:
---
layout: default
title: Hank Quinlan, Horrible Cop
---
<div class="blurb">
<h1>Hi there, I'm Hank Quinlan!</h1>
<p>I'm best known as the horrible cop from <em>A Touch of Evil</em> Don't trust me. <a href="/about">Read more about my life...</a></p>
</div><!-- /.blurb -->
Notice the plain text at the top of the file. Jekyll calls this the Front-matter. Any file on your site that contains this will be processed by Jekyll. Every time you commit a file that specifies layout: default at the top, Jekyll will magically generate the full HTML document by replacing {{ content }} in _layouts/default.html with the contents of the committed file. Awesome!
Setting up a Blog
A Jekyll-based blog uses the same conventions that we’ve familiarized ourselves with in the previous steps, but takes things further by adding a few more for us to follow. Jekyll is very flexible allowing you to extend your site as you wish, but in this guide we’re only going to cover the basics: creating a post, making a page to list our posts, creating a custom permalink for posts, and creating an RSS feed for the blog.
We’ll want to create a new layout for our blog posts called post.html and a folder to store each individual post called _posts/.
11 Start by creating the layout. Create a file named post.html in your _layouts folder. Notice the post layout uses the default layout as it’s base, and adds a couple new liquid tags to print the title of the post and date:
---
layout: default
---
<h1>{{ page.title }}</h1>
<p class="meta">{{ page.date | date_to_string }}</p>
<div class="post">
{{ content }}
</div>
12 Make a _posts/ directory where we’ll store our blog posts. Inside that folder will be our first post. Jekyll is very strict with how these files are named, so pay attention. It must follow the convention YYYY-MM-DD-title-of-my-post.md. This file name gets translated into the permalink for the blog post. So in this example, we’ll create a file named 2014-04-30-hank-quinlan-site-launched.md:
---
layout: post
title: "Hank Quinlan, Horrible Cop, Launches Site"
date: 2014-04-30
---
Well. Finally got around to putting this old website together. Neat thing about it - powered by [Jekyll](http://jekyllrb.com) and I can use Markdown to author my posts. It actually is a lot easier than I thought it was going to be.
Note the file extension .md stands for Markdown, and the Markdown syntax used inside the file gets converted to HTML by Jekyll. Like Wikitext, Markdown is a markup language with a syntax closer to plain text. The idea of Markdown is to get out of the author’s way so they can write their HTML content quickly, making Markdown very suitable as a blog authoring syntax. If you aren’t already, you’ll want to get familiar with Markdown syntax, and this printable cheatsheet (PDF) will be your best friend.
After committing the new post, navigate to http://username.github.io/YYYY/MM/DD/name-of-your-post to view it.
All this is great, but your readers won’t always know the exact URLs of your posts. So next we need to create a page on our site that lists each post’s title and hyperlink. You could create this list on your homepage or alternatively, create a blog subpage that collects all of your posts. We’re going to do the latter.
13 Create a blog directory and create a file named index.html inside it. To list each post, we’ll use a foreach loop to create an unordered list of our blog posts:
---
layout: default
title: Hank Quinlan's Blog
---
<h1>{{ page.title }}</h1>
<ul class="posts">
{% for post in site.posts %}
<li><span>{{ post.date | date_to_string }}</span> » <a href="{{ post.url }}" title="{{ post.title }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
Now checkout http://username.github.io/blog/. You should see your first post listed and linked there. Nice job!
Customizing Your Blog
We’ve only begun to scratch the surface with Jekyll’s blog aware functionality. This guide is only going to cover a couple more steps you might want to take for your blog.
You may have noticed that the URL of your blog post does not include the blog directory in it. In Jekyll we can control the structure of our permalinks by editing the _config.yml file we created in Step 8. So let’s change our permalink structure to include the blog directory.
14 Edit the _config.yml file. Add the following line at the end of the file:
permalink: /blog/:year/:month/:day/:title
Now you’re blog posts will live at http://username.github.io/blog/YYYY/MM/DD/name-of-your-post.
It is also very easy to setup an RSS feed for your blog. Every time you publish a new post, it will get added to this RSS file.
15 Inside your blog/ directory create a file and name it atom.xml. Add this to file:
---
layout: feed
---
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Hank Quinlan's Blog</title>
<link href="http://hankquinlan.github.io/blog/atom.xml" rel="self"/>
<link href="http://hankquinlan.github.io/blog"/>
<updated>{{ site.time | date_to_xmlschema }}</updated>
<id>http://hankquinlan.github.io/blog</id>
<author>
<name>Hank Quinlan</name>
<email>hankquinlanhub@gmail.com</email>
</author>
{% for post in site.posts %}
<entry>
<title>{{ post.title }}</title>
<link href="http://hankquinlan.github.io{{ post.url }}"/>
<updated>{{ post.date | date_to_xmlschema }}</updated>
<id>http://hankquinlan.github.io/{{ post.id }}</id>
<content type="html">{{ post.content | xml_escape }}</content>
</entry>
{% endfor %}
</feed>
Now you can include a link to your RSS feed somewhere on your site for users to subscribe to your blog in their feed aggregator of choice. Navigate to http://username.github.io/blog/atom.xml to view your feed.
Note: In Chrome, your feed might look like an error, but it isn’t. Chrome doesn’t know how to display XML.
Wrapping Up
16 You’re almost done! Don’t forget to create and commit your about/index.html and cv/index.html pages. Since I’m sure you’ve got the hang of things now, I’ll back off and let you get these pages finished on your own.
17 Before going any further, take the time to setup Git and Jekyll on your own computer. This tutorial is all about Git in the web browser, so really it’s only the half way point. You’re going to have to do this if you want to be able to upload image or PDF files to your GitHub repo. GitHub’s tutorials and desktop application make local setup easy, and now that you know many of Git and GitHub’s basic concepts, you should be able to get this going. Go do it!
Next Steps
Hopefully this guide has given you the confidence to do many other things with Git, GitHub, Jekyll, and your website or blog. You could go in many different directions at this point, as I’m sure you’ve already started thinking about, but here are a few other things I think would be worth your time:
Resources
I’ll try to keep this list current and up to date. If you know of a great resource you’d like to share or notice a broken link, please get in touch.
Git, GitHub, and GitHub Pages
Jekyll
Markdown
Notes
1. Somasundaram, R. (2013). Git: Version Control for Everyone (pp. 9-17). Birmingham, UK: Packt Publishing.
January 29, 2016
markdown
CommonMark
Source
What is Markdown?
It’s a plain text format for writing structured documents, based on formatting conventions from email and usenet.
Learn Markdown in 60 Seconds
Who created Markdown?
It was developed in 2004 by John Gruber, who wrote the first markdown-to-html converter in Perl, and it soon became widely used in websites. By 2014 there were dozens of implementations in many languages.
Why is CommonMark needed?
John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously.
In the absence of a spec, early implementers consulted the original Markdown.pl code to resolve these ambiguities. But Markdown.pl was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. Markdown.pl was last updated December 17th, 2004.
Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using Pandoc). To make matters worse, because nothing in Markdown counts as a “syntax error,” the divergence often isn’t discovered right away.
There’s no standard test suite for Markdown; MDTest is the closest thing we have. The only way to resolve Markdown ambiguities and inconsistencies is Babelmark, which compares the output of 20+ implementations of Markdown against each other to see if a consensus emerges.
We propose a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown.
That’s what we call CommonMark. 
Who are you?
We’re a group of Markdown fans who either work at companies with industrial scale deployments of Markdown, have written Markdown parsers, have extensive experience supporting Markdown with end users — or all of the above.
How can I help?
Exercise our reference implementations, or find a community implementation in your preferred environment or language. Provide feedback!
If a CommonMark implementation does not already exist in your preferred environment or language, try implementing your own CommonMark parser. One of our major goals is to strongly specify Markdown, and to eliminate the many old inconsistencies and ambiguities that made using Markdown so difficult. Did we succeed?
Where can I find it?
The CommonMark specification.
Reference implementation and validation test suite on GitHub.
Public discussion area and mailing list via Discourse.
Quick reference card and interactive tutorial for learning Markdown.
Live testing tool powered by the reference implementation.
When is the spec final?
The current version of the CommonMark spec is complete, and quite robust after a year of public feedback … but not quite final.
With your help, we plan to announce a finalized 1.0 spec and test suite in early 2016.
November 23, 2015
privacy security
AdNauseam: Baffle Web Trackers by Obfuscating Your Movements Online
Source
Online ad networks and search engines love it when you surf around. Everything you do—every page you load, every query you type—helps them build a profile of you, the better to sell ads targeting your interests. Spy agencies are probably also happy to track your online moves.
But today they’re all having trouble figuring me out, thanks to some sneaky browser plug-ins. One, AdNauseam, clicks every ad on every page I visit, baffling ad networks. When I do a search, TrackMeNot sends a stream of fake queries in the background—like “conan o’brien” and “watch tokyo samsung”—so Google and Bing can’t easily profile me either.
This is “obfuscation,” and it’s a fascinating development in our relationship to online surveillance.
“We want everyone to benefit from this amazing online technology, but we want to impose constraints on it,” says Helen Nissenbaum, director of the Information Law Institute at New York University and a leading thinker in the field of obfuscation. “Right now the technology is stacked against you.” Working with programmers overseas, Nissenbaum has spent the past decade crafting apps like AdNauseam and TrackMeNot, and this fall she published a book on why obfuscation is a strategy for modern life.
Reason one: It’s increasingly hard to “opt out” of online tracking. “Unless you want to go live in a cave away from society,” Nissenbaum notes, you need to be online—often for work or to access government services. Online services claim they’re voluntary, but the cost of being a refusenik grows every day.
In this context, obfuscation is a clever judo move. It’s a way for people in a relatively weak position—which is to say all of us, compared with Google or Facebook—to fight back. You exploit your adversaries’ inherent weakness: their insatiable appetite for data.
Obfuscation has a long pedigree. Airplanes in World War II dropped chaff to confuse enemy radar. WikiLeaks has been known to generate fake traffic as cover for leakers who are uploading documents to the site. In all cases, the key to obfuscation, says Vincent Toubiana, a developer of TrackMeNot, “is to create noise.”
As you might imagine, the folks in power are unthrilled by this monkey-wrenching. (One executive of an ad-supported site harshly criticized Nissenbaum at a talk she gave.) Obfuscation, they say, is a form of unfair “free riding.” Search engines use tracking to improve the overall quality of results—so TrackMeNot users get those benefits without contributing their own personal data. Nissenbaum and her coauthor, Finn Brunton, think obfuscators are in the clear as long as their tools are open to everyone and they don’t make other users worse off.
A bigger problem with obfuscation is that it doesn’t curtail online tracking. Only legislation could do that, and it’s pretty unlikely to come about. Nor is obfuscation, as Nissenbaum and her collaborators hasten to point out, true security. To really hide from, say, a repressive government, you need unbreakable encryption.
But as a form of everyday protest, I love the concept. Indeed, I can imagine plenty more ways to conceal my tracks. How about a hack that generates fake GPS readings in mobile apps? If I’m going to be followed online all day, I might as well leave some digital chaff.
Email clive@clivethompson.net.
Go Back to Top. Skip To: Start of Article.
