Technical Blog - GitHub Pages Setup Instructions

Prerequisites

  • GitHub repository with GitHub Pages enabled
  • Domain name (optional, but recommended for professional blog)

GitHub Pages Setup

1. Repository Configuration

  1. Go to your repository settings on GitHub
  2. Navigate to “Pages” section
  3. Set source to “Deploy from a branch”
  4. Select branch: main (or master)
  5. Select folder: / (root)

2. Custom Domain Setup (Optional)

  1. Add a CNAME file to your repository root
  2. Add your domain name to the CNAME file
  3. Configure DNS at your domain provider:
    • For apex domain: Create A records pointing to GitHub’s IP addresses
    • For subdomain: Create CNAME record pointing to yourusername.github.io

3. GitHub Pages IP Addresses

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

4. DNS Configuration Examples

For Apex Domain (yourdomain.com)

Type: A
Name: @
Value: 185.199.108.153

Type: A  
Name: @
Value: 185.199.109.153

Type: A
Name: @
Value: 185.199.110.153

Type: A
Name: @
Value: 185.199.111.153

Type: CNAME
Name: www
Value: yourusername.github.io

For Subdomain (blog.yourdomain.com)

Type: CNAME
Name: blog
Value: yourusername.github.io

Local Development Setup

1. Install Ruby and Jekyll

# On Windows (using RubyInstaller)
# Download from https://rubyinstaller.org/

# On macOS (using Homebrew)
brew install ruby
gem install jekyll bundler

# On Ubuntu/Debian
sudo apt-get install ruby-full build-essential zlib1g-dev
gem install jekyll bundler

2. Install Dependencies

cd your-blog-directory
bundle install

3. Run Local Server

bundle exec jekyll serve
# or with drafts
bundle exec jekyll serve --drafts

Your site will be available at http://localhost:4000

Customization Guide

Update Site Configuration

Edit _config.yml:

  • Update title, description, url
  • Add your social media handles
  • Modify categories as needed

Add Your Information

Edit about.markdown:

  • Add your bio and background
  • Update social media links
  • Add your photo

Create New Posts

  1. Create files in _posts directory
  2. Use naming convention: YYYY-MM-DD-title.md
  3. Include proper front matter: 
    ---
layout: post
title: "Your Post Title"
date: YYYY-MM-DD HH:MM:SS -0000
categories: [category-name]
tags: [tag1, tag2, tag3]
author: "Your Name"
excerpt: "Brief description of your post"
---

Available Categories

  • homelab - Homelab Automation
  • cloud-azure - Cloud Technologies - Azure
  • cloud-aws - Cloud Technologies - AWS
  • ai-ml - AI & Machine Learning
  • devops - DevOps & Infrastructure
  • programming - Programming & Development

Content Guidelines

Writing Tips

  • Use clear, descriptive titles
  • Include code examples where relevant
  • Add screenshots and diagrams
  • Include relevant tags for better organization
  • Write engaging excerpts

SEO Best Practices

  • Use descriptive permalinks
  • Include meta descriptions
  • Optimize images with alt text
  • Link to related posts
  • Use proper heading structure

Code Syntax Highlighting

Supported languages include:

  • bash, shell, powershell
  • python, javascript, typescript
  • yaml, json, xml
  • sql, dockerfile
  • And many more…

Publishing Workflow

1. Write locally

bundle exec jekyll serve --drafts

2. Test thoroughly

  • Check all links work
  • Verify code examples
  • Test responsive design

3. Commit and push

git add .
git commit -m "Add new post: Your Post Title"
git push origin main

4. Verify deployment

  • Check GitHub Actions for successful build
  • Visit live site to confirm changes

Troubleshooting

Common Issues

  1. Build failures: Check GitHub Actions logs
  2. CSS not loading: Verify main.scss exists in assets/css/
  3. Domain not working: Check DNS propagation (can take 24-48 hours)
  4. 404 errors: Ensure file paths match exactly

Useful Commands

# Check Jekyll version
bundle exec jekyll --version

# Build site without serving
bundle exec jekyll build

# Clean build files
bundle exec jekyll clean

# Check for broken links
bundle exec jekyll doctor

Resources