Free Personal Blogs & Documentation Hosting with GitHub Pages

GitHub Pages is a static site hosting platform provided directly by GitHub for developers and open-source projects. Without purchasing dedicated cloud servers or configuring reverse proxies, you can publish static frontend assets to a designated branch and serve a website globally within seconds.

Whether you want to launch a developer portfolio, a technical blog (using Astro, VitePress, Hexo, or Hugo), or project documentation, GitHub Pages offers a zero-cost, high-reliability solution.

This tutorial covers GitHub Pages architecture, publishing approaches, custom domain mapping, and automatic HTTPS certificate provisioning.

1. Site Types & Naming Standards

GitHub Pages supports two distinct site tiers:

Site Type	Repository Naming Format	Live URL	Quota
User/Organization Site	`<username>.github.io`	`https://<username>.github.io`	1 per account
Project Site	Any valid repository name (e.g. `my-project`)	`https://<username>.github.io/my-project`	Unlimited (one per repo)

Note: For personal portfolio sites or main engineering blogs, name the repository exactly <username>.github.io.

2. Approach 1: Plain HTML Quickstart (5-Minute Deployment)

If you have pre-existing HTML, CSS, and JavaScript files, publish directly from a repository branch:

Create a public repository named <username>.github.io.

Add an index.html file to the root directory:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Developer Homepage</title>
  <style>
    body { font-family: -apple-system, sans-serif; text-align: center; padding: 50px; }
    h1 { color: #10b981; }
  </style>
</head>
<body>
  <h1>Welcome to My GitHub Space!</h1>
  <p>Hosted effortlessly with GitHub Pages.</p>
</body>
</html>

Commit and push the file to the main branch.
Go to repository Settings -> Pages:
- Source: Select Deploy from a branch.
- Branch: Choose main and / (root).
- Click Save.
Within 1 to 2 minutes, your website is live at https://<username>.github.io.

3. Approach 2: Modern Static Site Generators via GitHub Actions

For modern frameworks (such as Astro, VitePress, Hexo, or Next.js static exports), avoid committing build artifacts manually. Use GitHub Actions to compile and deploy on every git push.

Create .github/workflows/deploy.yml:

name: Deploy GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Under repository Settings -> Pages, change the Source selector to GitHub Actions. Pushing updates to Markdown content or codebase will rebuild and publish your site automatically.

4. Custom Domains & Automated HTTPS Provisioning

To connect a custom domain (such as blog.example.com or example.com):

Step 1: Configure DNS Records at Your DNS Provider

For a Subdomain (e.g. blog.example.com):
- Type: CNAME
- Host / Name: blog
- Value / Target: <username>.github.io
For an Apex / Root Domain (e.g. example.com):
- Type: A record
- Value: Add the four official GitHub Pages Anycast IPs:
  - 185.199.108.153
  - 185.199.109.153
  - 185.199.110.153
  - 185.199.111.153

Step 2: Configure Custom Domain in GitHub

In your repository, go to Settings -> Pages.
Enter your domain into the Custom domain field (e.g. blog.example.com) and click Save.
A CNAME file is added automatically to your branch root.
Once DNS verification succeeds, check Enforce HTTPS. GitHub provisions and automatically renews a free Let’s Encrypt TLS certificate.

5. Quotas & Operational Guidelines

GitHub Pages is free of charge with the following reasonable use parameters:

Repository Size: Recommended under 1 GB.
Monthly Bandwidth: Soft ceiling of 100 GB per month.
Build Duration: Up to 10 minutes per automated build run.
Acceptable Use: Strictly intended for legitimate personal, academic, or project documentation hosting.