How to Deploy Your Website for Free Using GitHub Pages: A Complete Beginner’s Guide
📘 Chapter 4: Customization and Advanced Configurations
🧭 What You’ll Learn
This chapter covers how to go beyond basic deployment and
make your GitHub Pages site stand out. You’ll learn:
- How
to add a custom domain and enforce HTTPS
- How
to integrate a Jekyll theme or create a blog
- Ways
to customize appearance with CSS and JS
- GitHub
Pages configuration using _config.yml
- How
to set up project documentation sites
- SEO,
favicon, analytics, and third-party integration
🌐 Adding a Custom Domain
A custom domain replaces the default
username.github.io/repo-name URL with something more professional like
www.mysite.com.
🪜 How to Add a Custom
Domain
Step 1: Purchase a domain
Use providers like:
- Namecheap
- GoDaddy
- Google
Domains
Step 2: Point DNS to GitHub
Set a CNAME for www:
lua
www CNAME
username.github.io
If you want root domain support:
less
@ A 185.199.108.153
@ A 185.199.109.153
@ A 185.199.110.153
@ A 185.199.111.153
Step 3: Create a CNAME file in your repo
At the root of your repo (or /docs):
CNAME
www.mysite.com
GitHub will automatically detect and link your domain.
SSL/HTTPS support usually activates within 24 hours.
🔐 Enforcing HTTPS
Ensure that your website is secure by turning on HTTPS.
- Navigate
to Settings > Pages
- Scroll
to “Custom domain”
- Check
“Enforce HTTPS”
This forces all visitors to access the site securely (via
https://).
🎨 Customizing Appearance
with Themes
GitHub Pages supports Jekyll, a static site generator
that uses Markdown and layouts. You can quickly apply beautiful themes.
✅ Adding a Jekyll Theme
- Create
_config.yml at the root of your repo
- Add
a theme like this:
yaml
theme:
minima
- Commit
the file and refresh the page
GitHub will use this theme to render your site if you're
using Markdown (.md) files.
🧱 Popular GitHub Pages
Themes
|
Theme |
Description |
|
Minima |
Clean, minimal
blogging theme |
|
Cayman |
Project or
product-focused layout |
|
Slate |
Documentation style |
|
Hacker |
Programmer-focused
appearance |
|
Midnight |
Dark background, light
text |
You can browse more here: https://pages.github.com/themes/
✍️ Writing Markdown with Jekyll
With Jekyll and themes, you can write content in Markdown
and GitHub will convert it into HTML.
example.md
markdown
---
layout:
default
title:
My First Post
---
#
Hello World
Welcome to my first blog post using GitHub Pages and
Markdown!
⚙️ Advanced Configuration with
_config.yml
The _config.yml file customizes how Jekyll builds your site.
🧾 Sample _config.yml
yaml
title:
My Portfolio
email:
john@example.com
description:
>-
This is my personal website hosted with
GitHub Pages.
baseurl:
"" # for user sites; use "/repo-name" for project sites
url:
"https://johnsmith.github.io"
theme:
minima
show_excerpts:
true
📝 Key Properties
|
Key |
Purpose |
|
title |
Site title |
|
email |
Contact email |
|
description |
Short description for
metadata |
|
baseurl |
Needed for
project sites |
|
theme |
Jekyll theme name |
📃 Adding SEO Metadata
Add these tags to your <head> section in index.html:
html
<meta
name="description" content="My personal website and
portfolio">
<meta
name="author" content="John Smith">
<meta
name="keywords" content="portfolio, web developer,
resume">
Open Graph for Social Media
html
<meta
property="og:title" content="My Portfolio">
<meta
property="og:description" content="Welcome to my web developer
portfolio">
<meta
property="og:image"
content="https://example.com/preview.png">
🌟 Favicon and Branding
Upload a favicon.ico to the root of your project.
html
<link
rel="icon" type="image/x-icon"
href="/favicon.ico">
You can generate one using sites like favicon.io.
📊 Integrating Analytics
(Google Analytics)
Paste this in your index.html or _includes/head.html:
html
<!--
Google Analytics -->
<script
async
src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer
= window.dataLayer || [];
function
gtag(){dataLayer.push(arguments);}
gtag('js',
new Date());
gtag('config',
'G-XXXXXXXXXX');
</script>
Replace G-XXXXXXXXXX with your tracking ID.
🧩 Adding Third-Party
Widgets
You can embed:
- YouTube
videos
- GitHub
contributions
- Instagram
posts
- Disqus
comments
Embed YouTube
html
<iframe
width="560" height="315"
src="https://www.youtube.com/embed/dQw4w9WgXcQ"
frameborder="0"
allowfullscreen></iframe>
📂 Organizing Pages and
Navigation
Create additional HTML pages:
about.html
projects.html
contact.html
Use anchor links for navigation:
html
<nav>
<a
href="index.html">Home</a>
<a
href="about.html">About</a>
<a
href="projects.html">Projects</a>
</nav>
🔁 Multi-language Support
(Manual)
Use folders for different language versions:
bash
/en/index.html
/es/index.html
/fr/index.html
Then add a language switcher in your navigation.
🧪 Testing on Local
Machine
Install Jekyll to test your site before pushing:
bash
gem
install bundler jekyll
jekyll
new mysite
cd
mysite
bundle
exec jekyll serve
Open http://localhost:4000 to view your local version.
📘 Documentation Sites for
Projects
Great for open-source tools, APIs, and dev guides.
Folder Structure
arduino
project-docs/
├── index.md
├── getting-started.md
├── config.md
└── _config.yml
Set a theme like jekyll-theme-slate in _config.yml for
docs-style layouts.
🧼 Final Customization
Checklist
|
Task |
Done |
|
Custom domain set |
✅ |
|
HTTPS enforced |
✅ |
|
Jekyll theme added |
✅ |
|
SEO tags added |
✅ |
|
Google Analytics
configured |
✅ |
|
Additional pages created |
✅ |
|
Navigation working |
✅ |
|
Previewed locally (optional) |
✅ |
📊 Table: GitHub Pages
Customization Elements
|
Feature |
Tool/Method |
|
Theme support |
Jekyll via _config.yml |
|
Metadata/SEO |
HTML
<meta> tags |
|
Custom domain |
DNS + CNAME file |
|
Analytics |
Google
Analytics |
|
Navigation |
HTML links |
|
Markdown support |
Jekyll |
🔚 Summary
In this chapter, we explored advanced configuration options
to polish your GitHub Pages site:
- You
learned how to use custom domains, enable HTTPS, and embed tracking tools.
- You
explored Jekyll themes, Markdown blogging, and _config.yml tweaks.
- You
set up a complete custom navigation system, added SEO metadata, and
improved design.
Your GitHub Pages site is now professional, branded, and
optimized. 🚀
FAQs
❓ 1. What is GitHub Pages and how does it work?
Answer:
GitHub Pages is a free hosting service by GitHub that allows you to publish
static websites directly from a GitHub repository. It works by serving the
HTML, CSS, JS, and other static files from your repo to a web URL like
https://yourusername.github.io/.
❓ 2. Is GitHub Pages really free to use?
Answer:
Yes, GitHub Pages is completely free. There are no hidden fees, and you can
host as many static sites as you want as long as your repository is public.
Private repo hosting is available with GitHub Pro.
❓ 3. What kind of websites can I host on GitHub Pages?
Answer:
You can host static websites, such as portfolios, documentation, blogs,
resumes, and simple landing pages. It does not support server-side languages
like PHP, Python, or databases.
❓ 4. What file should my website start with for GitHub Pages to work?
Answer:
Your site should have an index.html file in the root directory (or /docs if
using that folder). This acts as the homepage for your site.
❓ 5. How long does it take for my GitHub Pages site to go live?
Answer:
Typically, your site is live within 30 seconds to 2 minutes after
enabling GitHub Pages. However, DNS changes (like custom domains) may take up
to 24 hours.
❓ 6. Can I use a custom domain with GitHub Pages?
Answer:
Yes! You can map a custom domain by updating your DNS settings and adding a
CNAME file to your repository with your domain name in it (e.g.,
www.yoursite.com).
❓ 7. Can I use GitHub Pages with frameworks like React or Vue?
Answer:
Yes, you can build your project and push the static build/ folder to
your GitHub repo. Some projects use the /docs folder for this or deploy using
GitHub Actions for automation.
❓ 8. How do I fix broken links or missing styles/scripts?
Answer:
Check if your file paths are correct and relative (e.g., ./style.css instead of
/style.css). Also, make sure your files are in the correct directories and
committed to the repo.
❓ 9. Can I use GitHub Pages for private projects?
Answer:
You can only host public repos for free with GitHub Pages. For private repo
hosting, you’ll need a GitHub Pro plan or use GitHub Actions to deploy
elsewhere (like Netlify).
❓ 10. What are some alternatives to GitHub Pages?
Answer:
Other free static hosting options include:
- Netlify
- Vercel
- Firebase
Hosting
- Cloudflare Pages
These services offer more flexibility for dynamic apps,
CI/CD, and advanced routing.
Comments(0)