When seeking information, we typically turn to the internet and utilize specific keywords for our search. While numerous blog posts are available, a significant portion of them reiterate the same information redundantly. Consequently, when I contemplated creating my own posts, I hesitated to contribute yet another to the pool. Nonetheless, I recognized the value of having a repository to store and easily revisit the knowledge I acquire. Furthermore, by sharing it, others in need of similar information can also reap the benefits. I trust that you’ll discover something valuable within these articles.
In this post, I’ll explain how I made my blog and added information to it. I’ve experimented with various tools before, such as Hugo, Jekyll, and Gridsome. Eventually, I settled on Jekyll because I came across a fantastic Jekyll theme called “Chirpy” in the theme gallery. This theme is minimal, responsive, and packed with features specifically designed for technical writing. Also the project is actively maintained. Now, let’s delve into the process of installing Jekyll and configuring the Chirpy theme.
Install Prerequisites
Jekyll is a Ruby Gem that can be installed on most systems. so you will have to install ruby and some prerequisites apps. This can be done by running the command:
1
sudo apt-get install ruby-full build-essential zlib1g-dev
Add ENV variables
The following commands will add environment variables to your ~/.bashrc file to configure the gem installation path.
1
2
3
4
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Install Jekyll and bundler
Install Jekyll and Bundler using the below command.
1
gem install jekyll bundler
Creating a New Site
Sign in to GitHub and browse to Chirpy Starter, click the button Use this template > Create a new repository, and name the new repository USERNAME.github.io, where USERNAME represents your GitHub username.
While some suggest creating a public repository as USERNAME.github.io, it’s wise to keep the configuration private and copy only the build output’s contents to the public repository. This ensures you share only what you intend.
Installing Dependencies
Before running local server for the first time, go to the root directory of your site and run
1
bundle
Update Configuration
Update the variables of _config.yml as needed. The file can be found at the root of the repository.
Create new posts
For Jekyll to render correctly, the file names must be in certain format and the conent should include some metadata. I use the below script for creating new posts which will create a new file based on user inputs. Later you can edit the new file add your content to it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#!/bin/bash
# Get current date, year, and month
DATE=$(date +"%Y-%m-%d")
YEAR=$(date +"%Y")
MONTH=$(date +"%m")
DATEFORPOST=$(date -u '+%Y-%m-%d %H:%M:%S %z')
# Get title from user input
echo "Enter the post title:"
read TITLE
echo "Enter the post slug:"
read SLUG
# Create year and month directories if they don't exist
mkdir -p _posts/$YEAR/$MONTH
# Create the file with YAML frontmatter
cat > _posts/$YEAR/$MONTH/$DATE-$SLUG.md <<EOL
---
title: "$TITLE"
date: $DATEFORPOST
categories:
- technical-writing
- AI
tags:
- azure
- kubernetes
keywords:
description: ""
---
EOL
Running Local Server
You may want to preview the site contents before publishing, so just run
1
bundle exec jekyll s
After a few seconds, the local service will be published at http://127.0.0.1:4000.
Build and Deploy
Go to the root of the source project, and build your site as follows:
1
JEKYLL_ENV=production bundle exec jekyll b
Unless you specified the output path, the generated site files will be placed in folder _site of the project’s root directory. Now you should upload those files to the target server. Commit the changes and push to the github repository.
If you prefer to keep your configuration and shareable content separate, then copy the contents of the _site folder to a separate repository named USERNAME.github.io. Although GitHub free accounts require USERNAME.github.io to be public, you can still maintain the configuration repository as private.
Create a Github pages Site
Github has it well documented here at this link. Follow the instructions and publish your site
Configure Custom Domain
If you would like to add a custom domain, you can do so by following the steps from here