Warning: This how-to is for Mac users, since it provides information on installing Mac OS X apps. Windows is quite similar though, you’ll have to google.

What is GitHub?

GitHub is a platform for hosting and collaborating on projects.

Say you want to create a cool handmade visualisation or a webpage template or a scraper (as opposed to using automated but limited tools with user-interface, like Datawrapper, CartoDB, Shorthand). You’ll need to code the whole thing yourself – and you’ll want to store all the code and documentation in one place online. That’s GitHub. Not only does it store your files but it also remembers all the changes you make – it’s called version control – so you can always go back to an earlier stage and correct errors.

GitHub is also cool because it makes your work open source, i.e. free for others to share, use and improve. In return, you’ll be able to use the gems put on GitHub by others. Search for them and, yes, copy (‘fork‘) and reuse (if you can). Or ‘star‘ for later.

Although GitHub is far from being a Content Management System (like WordPress or Adobe CQ), you can host a blog on GitHub, or publish your amazing handmade projects as standalone GitHub Pages. No worries if that seems intimidating, though; thanks to its open source ideology, why not just start by inputting your data into somebody else’s template? It’s a great way to learn.

Blogging via GitHub is geeky.  There is no database where you can access all your posts and make changes in minutes. You’ll need to use some magic to post (see below). But the value for money (it’s free) is great – you can make your blog and its features look however you want. With some extra magic like Heroku, you can publish interactives of any complexity (compare to the limitations of a platform like Wordpress.com). But for a start, you may well choose one of the suggested themes.

Why bother?

You may think, ‘Why should I bother going the hard route if I can’t really code (yet)?’ Makes sense. But maybe, like me, you decided to take up the challenge early instead of postponing it ‘until I finally learn coding’ (=forever). I decided to fight my dev ignorance along the way because it’s much more fun (and better motivation) to learn things when you need them in real projects rather than to start from the very (boring and theoretical) beginning.

My friend Martin Gonzalez taught me how to use GitHub a while ago, and here I have put down the key steps as simply as I could. Follow them and you’ll be fine. Well, there might be a few hitches, but it’s worth a try!

There are only two types of people, a good old dev colleague told me: a developer (everything works) and a tester (everything fails). Test who you are.

Let’s start by setting it up

1. Go to GitHub.com and sign up

As easy as registering for Facebook. Choose a free plan obviously. (Later on, don’t forget to add a nice pic of yourself and some About Me wording).

You’ll arrive at this start page:

Just registered
Just registered

GitHub has very user-friendly guides and help pages. Take 10 mins to read this intro guide on basic activities in GitHub.

2. Create your first repository

To keep your files in order, you’ll store each project in a separate space called a ‘repository’.

Once you’re registered, GitHub will offer to create one. If not, use ‘+ New repository’ button.

Choose these options:


Boom! You’re set.

3. Create your first GitHub Page

If you plan to publish your work with GitHub, remember that a free account allows having one site per GitHub account/organisation and unlimited project sites.

You can generate a one-page project-site automatically by following the simple steps in this guide (choose Project Site -> Generate a site).

Try publishing your CV, for example.

Generate a page
Generate a page
4. Work locally on your computer and sync changes with online

The smart guys say it works best. What you need to do now is to ‘clone’ your repository to your local machine, do whatever work you need and push the changes back online (you will actually need to push every new change – called ‘commit’ – because this allows GitHub to keep versions of your work).

I am sorry, but at this stage you need to do everything in Terminal. Type Terminal in Spotlight and open the app. It looks sweet, doesn’t it?

Terminal is a Unix command line programme – a magic window into the deep dark world of your computer’s internal system. Obviously, it’s here for you to give it commands, and it will obey.

For instance, (always) find a $ sign and type whoami after it. Press enter (always press enter and wait, however long it takes, for something to happen, at least an ERROR).


See, it obeys! I am shveda indeed.

If you have some extra patience, do check this Command Line Crash Course.

There is also a desktop app for managing GitHub but using a command line is honestly more straightforward.

5. Install GitHub Pages and other important packages to your computer

Before you can proceed to using a hipster GitHub, you’ll need to install some development packages on your Mac. It’s not too painful, just do it.


As Wiki explains, Xcode is an integrated development environment containing a suite of software development tools developed by Apple for developing software for OS X and iOS. You’re not going to develop an iPhone app today, but you still need it.

Simply search for Xcode in AppStore and install (or update) it for free. Warning: it’s a large app, so it’ll take ages to install. But you have no choice.

Xcode in AppStore (top left corner)

In case something goes wrong, check this installation guide.


Homebrew is a package manager for Mac OX. Installation is very straightforward – go to Homebrew website, it will tell you to paste this code into the command line of Terminal (just paste and enter):

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

The code should work without your help. In case of an error message, read what it says and google how to solve it. Probably, you’ll need to download an extra package like the ones above. Or if the error says you have no administrator rights, try typing ‘sudo‘ before any other command (sudo prompts the systems to ask for your password as an admin).

GitHub Pages

After the $ sign is back in Terminal, type this command:

gem install github-pages


6. Clone your repository to the computer

Finally, you can clone (make a copy of) your online repository to your computer. Go to the repository page on Github.com and copy its HTTPS clone URL in the bottom right corner of the page.

Clone repository
Clone repository

Go back to Terminal and type this command:

git clone https://github.com/dummy-student/myblog.git

(Use your own URL obviously).

As a result you will find a GitHub folder named after your repository in the Home folder of your Mac (Finder – Go – Home, if you’re lost).

Yay, you can start posting now!



Meanwhile, here are some words of the wise on the value of using GitHub for journalism:

For an alternative to my writing, try this video tutorial on GitHub for beginners.

Let us know how it went or what problems you’ve faced via Twitter!


  1. It would be nice to publish a list of profiles of great data journalists/news developers/coding journalists who are on Github. Great to follow people way ahead to learn. I’ve found a few but would love to find more!

Leave a Reply