{"rowid": 7, "title": "Get Started With GitHub Pages (Plus Bonus Jekyll)", "contents": "After several failed attempts at getting set up with GitHub Pages, I vowed that if I ever figured out how to do it, I\u2019d write it up. Fortunately, I did eventually figure it out, so here is my write-up.\n\nWhy I think GitHub Pages is cool\n\nNormally when you host stuff on GitHub, you\u2019re just storing your files there. If you push site files, what you\u2019re storing is the code, and when you view a file, you\u2019re viewing the code rather than the output. What GitHub Pages lets you do is store those files, and if they\u2019re HTML files, you can view them like any other website, so there\u2019s no need to host them separately yourself.\n\nGitHub Pages accepts static HTML but can\u2019t execute languages like PHP, or use a database in the way you\u2019re probably used to, so you\u2019ll need to output static HTML files. This is where templating tools such as Jekyll come in, which I\u2019ll talk about later.\n\nThe main benefit of GitHub Pages is ease of collaboration. Changes you make in the repository are automatically synced, so if your site\u2019s hosted on GitHub, it\u2019s as up-to-date as your GitHub repository. This really appeals to me because when I just want to quickly get something set up, I don\u2019t want to mess around with hosting; and when people submit a pull request, I want that change to be visible as soon as I merge it without having to set up web hooks.\n\nBefore you get started\n\nIf you\u2019ve used GitHub before, already have an account and know the basics like how to set up a repository and clone it to your computer, you\u2019re good to go. If not, I recommend getting familiar with that first. The GitHub site has extensive documentation on getting started, and if you\u2019re not a fan of using the command line, the official GitHub apps for Mac and Windows are great.\n\nI also found this tutorial about GitHub Pages by Thinkful really useful, and it contains details on how to turn an existing repository into a GitHub Pages site.\n\nAlthough this involves a bit of using the command line, it\u2019s minimal, and I\u2019ll guide you through the basics.\n\nSetting up GitHub Pages\n\nFor this demo we\u2019re going to build a Christmas recipe site \u2014 nothing complex, just a place to store recipes so we can share them with people, and they can fork or suggest changes to ones they like. My GitHub username is maban, and the project I\u2019ve set up is called christmas-recipes, so once I\u2019ve set up GitHub Pages, the site can be found here: http://maban.github.io/christmas-recipes/\n\nYou can set up a custom domain, but by default, the URL for your GitHub Pages site is your-username.github.io/your-project-name.\n\nSet up the repository\n\nThe first thing we\u2019re going to do is create a new GitHub repository, in exactly the same way as normal, and clone it to the computer. Let\u2019s give it the name christmas-recipes. There\u2019s nothing in it at the moment, but that\u2019s OK.\n\n\n\nAfter setting up the repository on the GitHub website, I cloned it to my computer in my Sites folder using the GitHub app (you can clone it somewhere else, if you want), and now I have a local repository synced with the remote one on GitHub.\n\nNavigate to the repository\n\nNow let\u2019s open up the command line and navigate to the local repository. The easiest way to do this in Terminal is by typing cd  and dragging and dropping the folder into the terminal window and pressing Return. You can refer to Chris Coyier\u2019s GIF illustrating this very same thing, from last week\u2019s 24 ways article \u201cGrunt for People Who Think Things Like Grunt are Weird and Hard\u201d (which is excellent).\n\nSo, for me, that\u2019s\u2026\n\ncd /Users/Anna/Sites/christmas-recipes \n\nCreate a special GitHub Pages branch\n\nSo far we haven\u2019t done anything different from setting up a regular repository, but here\u2019s where things change.\n\nNow we\u2019re in the right place, let\u2019s create a gh-pages branch. This tells GitHub that this is a special branch, and to treat the contents of it differently.\n\nMake sure you\u2019re still in the christmas-recipes directory, and type this command to create the gh-pages branch:\n\ngit checkout --orphan gh-pages\n\nThat --orphan option might be new to you. An orphaned branch is an empty branch that\u2019s disconnected from the branch it was created off, and it starts with no commits, making it a special standalone branch. checkout switches us from the branch we were on to that branch.\n\nIf all\u2019s gone well, we\u2019ll get a message saying Switched to a new branch \u2018gh-pages\u2019.\n\nYou may get an error message saying you don\u2019t have admin privileges, in which case you\u2019ll need to type sudo at the start of that command.\n\nMake gh-pages your default branch (optional)\n\nThe gh-pages branch is separate to the master branch, but by default, the master branch is what will show up if we go to our repository\u2019s URL on GitHub. To change this, go to the repository settings and select gh-pages as the default branch.\n\n\n\nIf, like me, you only want the one branch, you can delete the master branch by following Oli Studholme\u2019s tutorial. It\u2019s actually really easy to do, and means you only have to worry about keeping one branch up to date.\n\nIf you prefer to work from master but push updates to the gh-pages branch, Lea Verou has written up a quick tutorial on how to do this, and it basically involves working from the master branch, and using git rebase to bring one branch up to date with another.\n\nAt the moment, we\u2019ve only got that branch on the local machine, and it\u2019s empty, so to be able to see something at our special GitHub Pages URL, we\u2019ll need to create a page and push it to the remote repository.\n\nMake a page\n\nOpen up your favourite text editor, create a file called index.html in your christmas-recipes folder, and put some exciting text in it. Don\u2019t worry about the markup: all we need is text because right now we\u2019re just checking it works.\n\n\n\nNow, let\u2019s commit and push our changes. You can do that in the command line if you\u2019re comfortable with that, or you can do it via the GitHub app. Don\u2019t forget to add a useful commit message.\n\n\n\nNow we\u2019re ready to see our gorgeous new site! Go to your-username.github.io/your-project-name and, hopefully, you\u2019ll see your first GitHub Pages site. If not, don\u2019t panic, it can take up to ten minutes to publish, so you could make a quick cake in a cup while you wait.\n\nAfter a short wait, our page should be live! Hopefully that wasn\u2019t too traumatic. Now we know it works, we can add some proper markup and CSS and even some more pages.\n\nIf you\u2019re feeling brave, how about we take it to the next level\u2026\n\nSetting up Jekyll\n\nSince GitHub Pages can\u2019t execute languages like PHP, we need to give it static HTML files. This is fine if there are only a few pages, but soon we\u2019ll start to miss things like PHP includes for content that\u2019s the same on every page, like headers and footers.\n\nJekyll helps set up templates and turn them into static HTML. It separates markup from content, and makes it a lot easier for people to edit pages collaboratively. With our recipe site, we want to make it really easy for people to fix typos or add notes, without having to understand PHP. Also, there\u2019s the added benefit that static HTML pages load really fast.\n\nJekyll isn\u2019t officially supported on Windows, but it is still possible to run it if you\u2019re prepared to get your hands dirty.\n\nInstall Jekyll\n\nBack in Terminal, we\u2019re going to install Jekyll\u2026\n\ngem install jekyll\n\n\u2026and wait for the script to run. This might take a few moments. It might take so long that you get worried its broken, but resist the urge to start mashing your keyboard like I did.\n\nGet Jekyll to run on the repository\n\nFingers crossed nothing has gone wrong so far. If something did go wrong, don\u2019t give up! Check this helpful post by Andy Taylor \u2013 you probably just need to install something else first. \n\nNow we\u2019re going to tell Jekyll to set up a new project in the repository, which is in my Sites folder (yours may be in a different place). Remember, we can drag the directory into the terminal window after the command.\n\njekyll new /Users/Anna/Sites/christmas-recipes\n\nIf everything went as expected, we should get this error message: Conflict: /Users/Anna/Sites/christmas-recipes exists and is not empty.\n\nBut that\u2019s OK. It\u2019s just upset because we\u2019ve got that index.html file and possibly also a README.md in there that we made earlier. So move those onto your desktop for the moment and run the command again.\n\njekyll new /Users/Anna/Sites/christmas-recipes\n\nIt should say that the site has installed.\n\nCheck you\u2019re in the repository, and if you\u2019re not, navigate to it by typing cd , drag the christmas-recipes directory into terminal\u2026\n\njekyll cd /Users/Anna/Sites/christmas-recipes\n\n\u2026and type this command to tell Jekyll to run:\n\njekyll serve --watch\n\nBy adding --watch at the end, we\u2019re forcing Jekyll to rebuild the site every time we hit Save, so we don\u2019t have to keep telling it to update every time we want to view the changes. We\u2019ll need to run this every time we start work on the project, otherwise changes won\u2019t be applied. For now, wait while it does its thing. \n\nUpdate the config file\n\nWhen it\u2019s finished, we\u2019ll see the text press ctrl-c to stop. Don\u2019t do that, though. Instead, open up the directory. You\u2019ll notice some new files and folders in there. There\u2019s one called _site, and that\u2019s where all the site files are saved when they\u2019re turned into static HTML. Don\u2019t touch the files in here \u2014 they\u2019re the generated files and will get overwritten every time we make changes to pages and layouts.\n\nThere\u2019s a file in our directory called _config.yml. This has some settings we can change, one of them being what our base URL is. GitHub Pages will assume the base URL is above the project repository, so changing the settings here will help further down the line when setting up navigation links.\n\nReplace the contents of the _config.yml file with this:\n\nname: Christmas Recipes\nmarkdown: redcarpet\npygments: true\nbaseurl: /christmas-recipes\n\nSet up your files\n\nOverwrite the index.html file in the root with the one we made earlier (you might want to pop the README.md back in there, too). \n\nDelete the files in the css folder \u2014 we\u2019ll add our own later.\n\nView the Jekyll site\n\nOpen up your favourite browser and type http://localhost:4000/christmas-recipes in the address bar.\n\n\n\nCheck it out, that\u2019s your site! But it could do with a bit more love.\n\nSet up the _includes files\n\nIt\u2019s always useful to be able to pull in snippets of content onto pages, such as the header and footer, so they only need to be updated in one place. That\u2019s what an _includes folder is for in Jekyll. Create a folder in the root called _includes, and within it add two files: head.html and foot.html. \n\nIn head.html, paste the following:\n\n<!DOCTYPE html>\n<html>\n    <head>\n        <meta charset=\"utf-8\">\n        <title>{{ page.title }}</title>\n        <link rel=\"stylesheet\" href=\"{{ site.baseurl }}/css/main.css\" >\n    </head>\n    <body>\n\nand in foot.html:\n\n</body>\n</html>\n\nWhenever we want to pull in something from the _includes folder, we can use {% include filename.html %} in the layout file \u2014 I\u2019ll show you how to set that up in next step.\n\nMaking layouts\n\nIn our directory, there\u2019s a folder called _layouts and this lets us create a reusable template for pages. Inside that is a default.html file. \n\nDelete everything in default.html and paste in this instead:\n\n{% include head.html %}\n\n    <h1>{{ page.title }}</h1>\n\n    {{ content }}\n\n{% include foot.html %}\n\nThat\u2019s a very basic page with a header, footer, page title and some content. To apply this template to a page, go back into the index.html page and add this snippet to the very top of the file:\n\n---\nlayout: default\ntitle: Home\n---\n\nNow save the index.html file and hit Refresh in the browser. We should see a heading where {{ page.title }} was in the layout, which matches what comes after title: on the page itself (in this case, Home). So, if we wanted a subheading to appear on every page, we could add {{ page.subheading }} to where we want it to appear in our layout file, and a line that says subheading: This is a subheading in between the dashes at the top of the page itself.\n\nUsing Markdown for templates\n\nAnything on a page that sits under the closing dashes is output where {{ content }} appears in the template file. At the moment, this is being output as HTML, but we can use Markdown instead, and Jekyll will convert that into HTML. For this recipe site, we want to make it as easy as possible for people to be able to collaborate, and also have the markup separate from the content, so let\u2019s use Markdown instead of HTML for the recipes.\n\nTelling a page to use Markdown instead of HTML is incredibly simple. All we need to do is change the filename from .html to .md, so let\u2019s rename the index.html to index.md. Now we can use Markdown, and Jekyll will output that as HTML.\n\nCreate a new layout\n\nWe\u2019re going to create a new layout called recipe which is going to be the template for any recipe page we create. Let\u2019s keep it super simple.\n\nIn the _layouts folder, create a file called recipe.html and paste in this:\n\n{% include head.html %}\n\n\t<main>\n\n    \t<h1>{{ page.title }}</h1>\n\n    \t{{ content }}\n\n    \t<p>Recipe by <a href=\"{{ page.recipe-attribution-link }}\">{{ page.recipe-attribution }}</a>.</p>\n\n\t</main>\n\n\t{% include nav.html %}\n\n{% include foot.html %}\n\nThat\u2019s our template. The content that goes on the recipe layout includes a page title, the recipe content, a recipe attribution and a recipe attribution link.\n\nAdding some recipe pages\n\nCreate a new file in the root of the christmas-recipes folder and call it gingerbread.md. Paste the following into it:\n\n---\nlayout: recipe\ntitle: Gingerbread\nrecipe-attribution: HungryJenny\nrecipe-attribution-link: http://www.opensourcefood.com/people/HungryJenny/recipes/soft-christmas-gingerbread-cookies\n---\nMakes about 15 small cookies.\n\n## Ingredients\n\n* 175g plain flour\n* 90g brown sugar\n* 50g unsalted butter, diced, at room temperature\n* 2 tbsp golden syrup\n* 1 egg, beaten\n* 1 tsp ground ginger\n* 1 tsp cinnamon\n* 1 tsp bicarbonate of soda\n* Icing sugar to dust\n\n## Method\n\n1. Sift the flour, ginger, cinnamon and bicarbonate of soda into a large mixing bowl.\n2. Use your fingers to rub in the diced butter. Mix in the sugar.\n3. Mix the egg with the syrup then pour into the flour mixture. Fold in well to form a dough.\n4. Tip some flour onto the work surface and knead the dough until smooth.\n5. Preheat the oven to 180\u00b0C.\n6. Roll the dough out flat and use a shaped cutter to make as many cookies as you like.\n7. Transfer the cookies to a tray and bake in the oven for 15 minutes. Lightly dust the cookies with icing sugar.\n\nThe content is in Markdown, and when we hit Save, it\u2019ll be converted into HTML in the _site folder. Save the file, and go to http://localhost:4000/christmas-recipes/gingerbread.html in your favourite browser.\n\n \n\nAs you can see, the Markdown content has been converted into HTML, and the attribution text and link has been inserted in the right place.\n\n\nAdd some navigation\n\nIn your _includes folder, create a new file called nav.html. Here is some code that will generate your navigation:\n\n<nav class=\"nav-primary\" role=\"navigation\" >\n    <ul>\n        {% for p in site.pages %}\n        <li>\n        \t<a {% if p.url == page.url %}class=\"active\"{% endif %} href=\"{{ site.baseurl }}{{ p.url }}\">{{ p.title }}</a>\n        </li>\n        {% endfor %}\n    </ul>\n</nav>\n\nThis is going to look for all pages and generate a list of them, and give the navigation item that is currently active a class of active so we can style it differently.\n\nNow we need to include that navigation snippet in our layout. Paste {% include nav.html %} in default.html file, under {{ content }}.\n\nPush the changes to GitHub Pages\n\nNow we\u2019ve got a couple of pages, it\u2019s time to push our changes to GitHub. We can do this in exactly the same way as before. Check your special GitHub URL (your-username.github.io/your-project-name) and you should see your site up and running.\n\nIf you quit Terminal, don\u2019t forget to run jekyll serve --watch from within the directory the next time you want to work on the files.\n\nNext steps\n\nNow we know the basics of creating Jekyll templates and publishing them as GitHub Pages, we can have some fun adding more pages and styling them up.\n\n \n \n Here\u2019s one I made earlier\n\n\nI\u2019ve only been using Jekyll for a matter of weeks, mainly for prototyping. It\u2019s really good as a content management system for blogs, and a lot of people host their Jekyll blogs on GitHub, such as Harry Roberts\n\n\n\tBy hosting the code so openly it will make me take more pride in it and allow me to work on it much more easily; no excuses now!\n\n\nOverall, the documentation for Jekyll feels a little sparse and geared more towards blogs than other sites, but as more people discover the benefits of it, I\u2019m sure this will improve over time.\n\nIf you\u2019re interested in poking about with some code, all the files from this tutorial are available on GitHub.", "year": "2013", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2013-12-18T00:00:00+00:00", "url": "https://24ways.org/2013/get-started-with-github-pages/", "topic": null}