Building a Static Website with Ruby, Jekyll and GitHub Pages
Jekyll is an amazing Ruby gem that enables you to easily create a static website from scratch! It is a great resource if you’re looking to quickly set up a front end site, and is easy to use even if you’ve never coded with Ruby before. It takes just a few minutes to get a basic site up and running, in this guide I am going to show you how.
Initial Setup
The first step is to install Ruby, if you don’t already have it on your computer. Next, install the Jekyll and bundler gems by typing the following into your terminal:
gem install jekyll bundlerAfter those gems are installed, name the folder:
jekyll new iris-luneAnd it will be created. Navigate to the new directory by typing cd iris-lune and then, in the folder, enter:
jekyll serve --watchIt may be necessary to type
bundle exec jekyll serveto run the local server.Adding
--watchenables you to make changes to your code and see them reflected in the browser by refreshing and without having to restart your local server.
You should now see some output in your terminal like this:
jekyll serve starts a local server which enables you to see your site in the browser by going to http://localhost:4000/. Check out your fully functioning site!
By default, Jekyll comes with a gem called minima that includes some basic styling for the site. In Jekyll, there are many pre-made themes that can be installed as gems. A great resource for free and paid themes is https://jekyllthemes.io/. However, if you’d like to customize the theme and layout of your site, there are a few extra steps we’ll need to take in order to make that happen.
Basic Customization
If you only want to make minor changes to the layout, navigate to the _config.yml file in the root directory of your project. (NOTE: You will have to restart your server to see the changes you make here). Editing the fields in this file will change aspects of your website, as shown in the images below.
The base install of Jekyll includes a homepage, an about page, and a post page. Adding more pages is simple, all you have to do is create a new HTML or Markdown file in your root directory, add some text to the top of the file, and the pages will automatically be generated!
Those 5 lines at the top are all it takes to add new pages, update the nav bar, and change the header at the top of the page. The value you put in layout is which file in the _layouts folder is being used to render the page (more on this soon). The title is the text you want to show up on the nav bar and at the top of the page. And the permalink creates the route to that particular site (e.g. https://localhost:3000/contact).
If you’re happy with using the default theme, or want to use another pre-built one, you now know everything you need to build your site! Feel free to skip ahead to the hosting section from here. If you’d like more advanced styling and modifications, read the More Advanced Customization section.
More Advanced Customization
In order to update the CSS of your site, add or edit layouts that your site is built on, and to modify the header and footer files, we’ll need to add a few more folders to the base directory. In terminal, type open $(bundle show minima) to open a Finder window with the _includes, _layouts, _sass, and assets folders. Your site is currently using these files to render the site. Go ahead and copy these 4 folders and their contents to your project’s root directory. Now, any changes made to the files in these folders will be reflected in your site.
NOTE: Do not edit the files in the
_sitefolder, these files are automatically generated by Jekyll.
Hosting
GitHub Pages is a great (and free!) resource for hosting static websites. In order to get your new site hosted there, all you need to do is login to GitHub and create a new repository, then in your root directory, in terminal, type git init, and then, git remote add origin git@github.com:YOUR ACCOUNT NAME/Iris-Lune.git. After that, you just need to git add, git commit, and git push, and your site is now almost online!
Navigate to your repository page on GitHub and click the “Branch: master” button (located at the bottom left of the first image below).
Using the form, create a branch called “gh-pages”. Your new repository should look something like the above right picture. I’ve highlighted the Settings button because we’re going to navigate there to make the site live. Scroll down until you see the options in the left image below. In the “Source” drop down menu, select the gh-pages branch, wait a few seconds, then click on the link GitHub gives you. Congrats, your site is now live!
Modifying the Domain
At this point, you may have noticed that the domain for your site is a GitHub URL. In this case it is: https://evolfo.github.io/Iris-Lune/. Next up, I’ll show you how to use a custom domain and connect it to your GitHub hosted site. The first step is to purchase a domain. There are many domain providers, and any of them will work as long as they allow you to modify your DNS settings.
The next step is to add the domain you purchased into the custom domain form on the GitHub pages section of your GitHub repository settings and hit save. Then, follow the instructions in this GitHub guide to finish configuring your domain to redirect to the repository. Instructions vary a bit based on where you purchased your domain, so be sure to look up how to modify the DNS settings for your site. Once you’ve set that up it can take up to 24 hours for the changes to be reflected.
See the final result below (after some time spent customizing the site)!
Conclusion
Jekyll and GitHub pages make creating static websites easy, fast, and cheap. The only cost you’ll incur from this whole process is paying for your custom domain, which can be as little as $20 a year (or less). Once you become a master of these services, setting up a new website from scratch will only be a matter of minutes. I hope this guide has been helpful and I would love to see the sites you’ll make with this new knowledge!
Resources
- https://jekyllrb.com/ - Documentation for the Jekyll gem
- https://jekyllthemes.io/ - Resource for Jekyll themes
- https://pages.github.com/ - GitHub Pages
- https://help.github.com/en/articles/quick-start-setting-up-a-custom-domain - Setting up a custom domain on GitHub
