Jekyll with GitHub Pages for Beginners

Jekyll is a simple, blog-aware, static site generator that's perfect for creating websites and blogs. It's written in Ruby and uses a template language that makes it easy to customize.

Jekyll was created by Tom Preston-Werner in 2008 and has since become a popular choice for developers and non-developers alike. The GitHub Pages platform, which we'll be using in this tutorial, supports Jekyll out of the box.

With GitHub Pages, you can host your Jekyll site for free, and it's a great way to get started with web development without worrying about server costs or maintenance.

Worth a look: How to Host a Site on Github

You can write in your favorite editor, such as Sublime, Vim, or Atom, and create new Markdown blog posts in the _posts folder.

To start, you'll need to clone your repository to your local machine using the command `git clone [email protected]:yourusername/yourusername.github.io.git`, or use GitHub Mac to clone your repository.

To create a new post, simply add a new Markdown file in the _posts folder, naming it in the format `year-month-day-title.md`, and include the front matter at the top of the post.

Discover more: How to Create a Landing Page in Webflow

Commit the post's Markdown file and push it to your GitHub repository using the command `git commit -m "Added new blog post"` and `git push`.

That's it! Just wait for GitHub Pages to rebuild your website, which typically takes under 10 seconds, assuming you don't have a huge amount of content.

To install Jekyll, you'll need to have Ruby and Bundler installed. To install Bundler, run the command `gem install bundler`.

To install Jekyll, run the command `gem install jekyll`.

This is a basic requirement for setting up a Jekyll project on GitHub Pages.

You can customize your Jekyll website by editing the _config.yml file. This file contains all the settings for your website, including the name, description, avatar, and other options.

Making a change to _config.yml will force GitHub Pages to rebuild your website with Jekyll, and the rebuilt website will be viewable a few seconds later at https://yourusername.github.io.

To customize your website, update the variables in your _config.yml file and then commit the changes. You can also use a third-party GitHub content editor, such as Prose by Development Seed, to make editing easier.

Here are the three ways you can edit your website's files:

Common problem #5 is that you don't need to build your Jekyll website locally in order to customize and theme a Jekyll website. GitHub Pages does that for you.

You can change your website's name, description, avatar, and other options by editing the _config.yml file. This file contains all the settings for your Jekyll website and allows you to customize variables that are pulled into your theme when your website gets built.

The _config.yml file is located in the root directory of your repository and contains all the settings for your Jekyll website. You can specify your own variables here to be pulled in via template files across the website.

Making a change to _config.yml will force GitHub Pages to rebuild your website with Jekyll. The rebuilt website will be viewable a few seconds later at https://yourusername.github.io.

You can change your blog's files from here on in one of three ways:

Don't assume that you need to jekyll build the website locally in order to customize and theme a Jekyll website. GitHub Pages does that for you, as long as you place the files you want to be built in the master branch of your user repository or in the gh-pages branch of any other repository.

Here are the common ways to integrate external data with a Jekyll website:

To import your blog posts from WordPress, you'll need to export your data from WordPress using a plugin like Ben Balter's one-click WordPress to Jekyll Exporter, which exports all of your WordPress content as a ZIP file, including posts, images and meta data.

Related reading: Wordpress Web Page Design

This plugin converts the data to Jekyll's format where needed, making the process much smoother. Unfortunately, the other option is to export all content in the "Tools" menu of the WordPress dashboard, and then importing it with Jekyll's importer.

You'll then need to update your image references by copying the exported images to wherever you're hosting your images on your Jekyll blog, which could be in an /images folder or on a content delivery network.

Data files are a great way to store repetitive or website-specific data in Jekyll. This keeps your _config.yml file tidy and free of clutter.

You can store data in YAML and JSON files, and Jekyll will read them from the /_data/ folder. This allows you to use them in your templates just like other variables.

Large data sets can also be included in your Jekyll website using data files. For example, you could write a script to break down a big data set into JSON files and place them in your Jekyll website's /_data/ folder.

Serving Google Analytics data to Jekyll is a creative example of using data files to include large data sets. This can help you rank blog posts by popularity, making it easier for readers to find the most engaging content.

Discover more: How to Update a Github Using Golang

Collections in Jekyll allow you to define your own document types beyond the standard posts and pages.

With the launch of Jekyll 2.0, collections became a game-changer for customization.

You can use a collection to define a photo album, book, or portfolio, giving you more flexibility in organizing your content.

Collections are a powerful tool for creating custom document types, and they're perfect for showcasing specific types of content.

You might like: Web Page Design Types

To remove a configuration or customization, you'll need to delete the corresponding file or setting.

If you're using Jekyll, you can remove a configuration by deleting the relevant Markdown file.

You can deploy your Jekyll site to GitHub Pages by following the steps outlined in the GitHub Pages documentation. GitHub Pages work by looking at certain branches of repositories on GitHub, specifically user/organization and project pages.

Two basic types of GitHub Pages are available: user/organization and project pages. The way to deploy these two types of sites are nearly identical, except for a few minor details.

Curious to learn more? Check out: Project Web Page Design

While Windows is not officially supported, it is possible to install the github-pages gem on Windows. Special instructions can be found on the Windows-specific docs page.

To deploy your site, simply push any local changes onto the default branch, and the action will be triggered and the build will start. You can watch the progress and see any build errors by checking on the build status.

To see the live site, go to the Deployments tab on your repository, and click on the deployed site URL.

Here are the steps to deploy your site to GitHub Pages:

Your website will probably go live immediately. You can check by going to https://yourusername.github.io. Don't worry if it isn't live yet: the workflow will build and deploy your site again when you need to make further changes.

Building and publishing your Jekyll site with GitHub Pages is a straightforward process. You can trigger a build and deploy on push by committing changes to the default branch.

To monitor the build progress, check the build status using the "View by commit" or "Actions" tab. If all goes well, your built assets will be uploaded to GitHub Pages.

Here are the steps to create a new blog post and see it live on your site:

GitHub Pages will automatically rebuild your website, and your new blog post will be live in under 10 seconds.

Building and deploying your website is a crucial step in making it live and accessible to the world. You can trigger the build process by pushing local changes to the default branch, which will start the build and deploy your site to GitHub Pages.

To keep an eye on the progress, check the build status using one of two approaches: View by commit or the Actions tab. If everything goes smoothly, all steps will be green and your built assets will be uploaded to GitHub Pages.

You can see the live site by going to the Deployments tab on your repository and clicking on the deployed site URL. To make further changes to the site, simply commit to the default branch and push.

Here are the steps to deploy your site:

Publishing your first blog post is an exciting milestone in building your website. You'll start by editing the existing file, /_posts/2014-3-3-Hello-World.md, to replace the placeholder content with your own.

Delete the placeholder text and enter your own content. If you need a quick primer on writing in Markdown, check out Adam Pritchard’s cheat sheet.

You'll need to change the file name to include today's date and the title of your post. Jekyll requires posts to be named year-month-day-title.md.

Update the title at the top of the Markdown file. Those variables at the top of the blog post are called front matter, which specify the layout to use and the title of the blog post.

Additional front-matter variables exist, such as permalink, tags, and category.

To create new blog posts in the browser on GitHub.com, simply hit the “+” icon in /_posts/. Just remember to format the file name correctly and to include the front-matter block so that the file gets processed by Jekyll.

Jekyll has a couple of powerful, more advanced features that might help you if you’re looking to scale up your website from a simple blog.

One of these features is the ability to use Jekyll's built-in support for Sass, a preprocessor that allows you to write more efficient and maintainable CSS code.

This can be a game-changer for larger websites with complex designs, as it enables you to write more reusable and modular code.

You can also use Jekyll's Liquid templating engine to create custom layouts and designs for your website.

Liquid makes it easy to separate presentation logic from content, making it a great choice for building scalable websites.

Jekyll's support for internationalization (i18n) and localization (L10n) features also make it an attractive choice for websites that need to cater to a global audience.

This allows you to easily translate your website into multiple languages and adapt it to different regions and cultures.

You can pick from a wide range of Jekyll-Bootstrap themes or create your own. To install a new theme, use the general syntax $ gem install jekyll-themes name="cooltheme".

Jekyll-Bootstrap themes come with all the necessary files to get started, which are placed in your repository.

The base themes for a page and post are found in _includes/themes/twitter/. If you're familiar with HTML, these are the files to edit.

User Pages are a special feature on GitHub where you can create a custom website for yourself or your organization. This website lives in a special repository named after your account name, such as mojombo.github.io.

The repository must be named exactly like your account name, and the content from the master branch will be used to build and publish the website. GitHub Pages are initially configured to live under the username.github.io subdomain.

The repository should be dedicated to only the GitHub Pages files, and GitHub Pages overrides the “Site Source” configuration value, so make sure your files are in the root directory for the site to build correctly.

To get started with Jekyll-Bootstrap, you'll need to create a new project page. First, use git clone to get a copy of the jekyll-bootstrap repository on Github.

You can change the name of the directory from jekyll-bootstrap to your repository’s name, for example, myrepo.

Jekyll-Bootstrap is set up to be viewed locally at http://localhost:4000.

To keep your folder organized, create a new directory called /pages and store your markdown files there. This will help keep your files tidy and make it easier to manage your content.

You can add new pages using the rake command. This will create a new markdown file with the name you specify.

For example, creating a new file named contactme in the /pages directory will give you a clean and organized way to manage your static pages. Put all your markdown files in the /pages directory to keep everything in one place.

If you create a file with an .md extension in the /pages directory, it will be treated as a static page, just like a file in the root directory. This means you can easily create new pages without having to worry about complicated file structures.

Theming is a crucial part of creating a unique and engaging website. You can install new themes using the general syntax, which will place all the necessary files for the theme in your repository.

Jekyll-Bootstrap makes it easy to switch between themes, allowing you to quickly change up the look and feel of your site. To switch themes, simply use the command $ rake theme:switch name="cooltheme".

The base themes for a page and post are found in _includes/themes/twitter/, and if you're familiar with HTML, you can make changes to the .html files in this directory.

Images can be stored in an /images/ folder in the repository without causing performance problems.

Storing images in the /images/ folder keeps things simple and straightforward.

If your website is hosted on GitHub Pages, images will be served up by GitHub's super-fast content delivery network.

You can easily link to an image by using Markdown in your content, which is as simple as saving the image to the /images/ folder.

Curious to learn more? Check out: Simple Web Page Design

Let's get started with Jekyll and GitHub Pages. To create our Jekyll powered website, we'll start by forking a starting point directly on GitHub.com in the browser.

We can get up and running in a few minutes without installing any dependencies. Here's a step-by-step guide to get us started:

We'll use GitHub Pages to host our website for free, and then we can customize it to include our personal touches.

As a GitHub user, you're entitled to one free "user" website, which will live at https://yourusername.github.io. This space is ideal for hosting a Jekyll blog.

You can simply place your unbuilt Jekyll blog on the master branch of your user repository, and GitHub Pages will build the static website and serve it for you. You don't have to worry about the build process at all – it's all taken care of.

Your website will probably go live immediately, but if it isn't, Step 3 will force it to be built. You can check by going to https://yourusername.github.io.

To use certain features, you'll need to have admin permissions for a repository. This is required to create a GitHub Pages site with Jekyll.

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.

People with admin permissions can create a GitHub Pages site with Jekyll.

Karl Broman's Simple Site Repository is a great resource for creating User Pages and Project Pages.

You can clone his repository, called simple_site, from GitHub, similar to the jekyll-bootstrap repository.

He has provided excellent documentation on creating User Pages and Project Pages, so it's worth checking out his website for more details.

The process of using his repository works very similar to using jekyll-bootstrap.