YCOde

This blog is my personal online journal mostly an outlet for technical, programming-related posts. It's my way to capture key ideas and concepts I find interesting in the software programming world.

Download as .zip Download as .tar.gz View on GitHub

Github Pages Site With Jekyll Theme

Setup Github Pages site with Jekyll

Jekyll is a static site generator with built-in support for Github Pages. For more information about Jekyll, check this link

Prerequisites

  • github account (see this link) for creating a github account)
  • Jekyll requires the following
    • Ruby version 2.5.0 or higher
    • RubyGems
    • GCC and Make

see installation guide for more details.

Creating a repository for your site.

  1. Login to github with your github account.
  2. In the upper-right corner of any page, use the drop-down menu, and select New repository.
  3. Enter “jekyll-hello-world” for the name of the repository.
  4. Enter a short description for the newly created repository.
  5. Make the repository public.
  6. Initialize the repository with README.
  7. Create the the repository.

Creating a Jekyll site

  1. Run jekyll new PATH to create a new site in PATH 
    $ jekyll new jekyll-hello-world
:
New jekyll site installed in ./jekyll-hello-world
  2. Move into the new site directory 
    $ cd jekyll-hello-world

    The following files and configurations are generated.

    $ ls -1
404.html
Gemfile
Gemfile.lock
_config.yml
_posts
about.markdown
index.markdown
    • site source - directory where jekyll will read files.
    • _config.yml - contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site.
    • _post - location where your blog posts live. You typically write posts in Markdown, HTML is also supported.
    • _site - jekyll builds the site and outputs a static site to this location. This folder keeps updating everytime you make changes on your project. You can then copy the final output on this folder and put them over on a web server.
    • Gemfile and Gemfile.lock - are used by Bundler to keep track of the required gems and gem versions you need to build your Jekyll site. Gem-based themes make it easier for theme developers to make updates available to anyone who has the theme gem. When there’s an update, theme developers push the update to RubyGems.
    • 404.html, about.markdown and index.markdown - default web pages generated by jekyll.

  3. Let’s build the files and configurations and serve it up on your local web server. 
    $ bundle exec jekyll serve
Configuration file: ./jekyll-hello-world/_config.yml
         Source: ./jekyll-hello-world
    Destination: ./jekyll-hello-world/_site
 Incremental build: disabled. Enable with --incremental
   Generating... 
    Jekyll Feed: Generating feed for posts
                 done in 1.757 seconds.
 Auto-regeneration: enabled for './mysite'
 Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop
  4. View the new site. Open any browser and enter the server address http://127.0.0.1:4000/ or localhost:4000

Customizing

Note Front matter is a snippet of YAML placed between two triple-dashed lines at the start of a file. You can use front matter to set variables.

---
---

Edit the _config.yml file and set the following variables.

title: [The title of your blog]
description: [A short description of your blog's purpose]
author:
  name: [Your name]
  email: [Your email address]

Creating a post

To create a post, add a file to your _posts directory with the following format:

YEAR-MONTH-DAY-title.MARKUP

Where YEAR is a four-digit number, MONTH and DAY are both two-digit numbers, and MARKUP is the file extension representing the format used in the file. For example, the following are examples of valid post filenames:

2021-08-12-how-to-write-a-blog.md

All blog post files must begin with front matter which is typically used to set a layout or other meta data. For example of post:

---
layout: post
title:  "Hello World!"
---

Hello world!, this is my first Jekyll blog post.

You can add more posts to make your site more interesting.

Update the About page

Open the about.markdown file. Write something about you and what you do.

View the new site. Open any browser and enter the server address http://127.0.0.1:4000/ or localhost:4000 and have a look through your updated About page and blog posts.

Hosting on Github Pages

Configuring a publishing source for your GitHub Pages site.

  1. On GitHub, navigate to your site’s repository.
  2. Under your repository name, click Settings.
  3. In the left sidebar, click Pages.
  4. On Github Pages, select gh-pages branch as the publishing source.
  5. You site is published at https://username.github.io/repository/

Push your site to Github Pages site.

  1. Initialize you site as local git repository 
    $ git init
  2. checkout a new branch named gh-pages. Note that the publishing source for your project site is the gh-pages branch. 
    $ git checkout -b gh-pages
Switched to a new branch 'gh-pages'
  3. Update the index using the current content found in the working tree, to prepare the content staged for the next commit 
    $ git add .
  4. Create a new commit containing the current contents of the index and the given log message describing the changes. 
    $ git commit -m "add initial files for my new site"
  5. Push your local git repository for your site 
    git remote add origin https://username.github.io/repository.git
git push -u origin gh-pages
  6. View your site at https://username.github.io/repository/