I spent three hours debugging a GitHub Pages deployment last month before realizing I'd made a typo in my repository name. Three hours. So yeah, I'm qualified to tell you exactly how to avoid that frustration and get your website live for free.
GitHub Pages sounds too good to be true. Free hosting. Free SSL certificate. Integrates directly with your code. No ads. No storage limits (within reason). And honestly? It mostly lives up to the hype. But there's a learning curve that nobody talks about—and I'm going to walk you through it like I wish someone had done for me.
My Website
What GitHub Pages Actually Is (And Isn't)
GitHub Pages is GitHub's static site hosting service. That matters. Static means HTML, CSS, and JavaScript files only. No databases. No PHP. No server-side processing. If you're trying to build a full web app with user authentication and a backend, GitHub Pages isn't your answer. But for everything else? A portfolio. A blog. Documentation. A landing page. A resume site. Project showcase. It's genuinely excellent. Here's what surprised me: GitHub Pages works with Jekyll by default, but you don't *have* to use Jekyll. You can push raw HTML. You can use React if you build it first. You can use Next.js with static export. You can use Hugo, Hugo, or literally any static site generator. That flexibility is underrated. And the free tier is actually free. Not "free for the first month" or "free with limitations." Free, period. Custom domain, HTTPS, unlimited bandwidth (they won't say unlimited, but they'll serve massive amounts). I used to think this was a trap—that Microsoft owns GitHub now so they must be losing money on this somehow. But after two years of using it, I'm convinced this is just GitHub being genuinely useful to developers.The One Real Limitation
You need to know Git and GitHub. Or at least, you need to be willing to learn them. If you've never used version control, GitHub Pages will feel like a ten-step process for something that should take two. It's not hard—just unfamiliar. Also, GitHub Pages builds public repositories only (unless you're on GitHub Pro, which costs money). Your code is visible. If that bothers you, it's a factor.Setting Up GitHub Pages Step by Step
Step 1: Create a GitHub Account and Repository
Go to GitHub.com. Sign up if you haven't already. Then create a new repository. Name it exactly like this: `yourusername.github.io` That naming convention is critical. It's not optional. If you name it anything else, you'll have to configure it differently (and most tutorials won't match what you're trying to do). I learned this by naming my first repo `my-portfolio` and then spending 20 minutes wondering why my site wasn't loading at the expected URL. Make it public. Add a README if you want, though it doesn't matter for hosting.Step 2: Clone the Repository to Your Computer
Open your terminal or command prompt. If you don't have Git installed, install it first (it's free). Then run: ``` git clone https://github.com/yourusername/yourusername.github.io.git cd yourusername.github.io ``` Now you're inside the folder. This is where your website files will live.Step 3: Add Your Website Files
Create an `index.html` file in this folder. The simplest possible version: ```htmlHello, world!
This is my first website on GitHub Pages.
``` Save it. Seriously, that's enough to start.Step 4: Push Your Files to GitHub
Back in your terminal: ``` git add . git commit -m "Initial commit" git push origin main ``` That's it. You've pushed your files. Now wait 30 seconds to 2 minutes. Then go to `https://yourusername.github.io` in your browser. Your site should be live.
Pro Tip: If your site doesn't appear immediately, GitHub Pages is building it. Check the "Settings" tab in your repository, scroll to "Pages," and see if there's a build status. GitHub will show you if there's an error. Most of the time it's something silly like a syntax error in your HTML.
Making It Look Professional Without Extra Hassle
Option 1: Write HTML and CSS Yourself
If you like control and don't mind writing code, just build it. Create separate `styles.css` and `script.js` files. Reference them in your HTML. Push to GitHub. Done. This takes longer, but you own every pixel.Option 2: Use a Static Site Generator
Jekyll is the easiest because GitHub Pages runs it automatically. No build step required. You just write Markdown, push, and it generates the HTML for you. But Jekyll has a learning curve. Configuration files. Liquid templating. It's not hard, but it's another layer. I used to recommend everyone start with Jekyll. Now I don't. Here's why: if you're not comfortable with coding already, Jekyll adds friction. You're learning Jekyll *and* Git *and* GitHub at the same time. That's too much. Hugo or Next.js are better if you want static generation, but you need to build locally and push the output. More steps, but cleaner process.Option 3: Use a Template (Honestly Just Fine)
There are free HTML templates everywhere. Download one. Customize it. Push to GitHub. You'll have a professional-looking site in 30 minutes. Is it original? No. But it works, and you can iterate from there.Custom Domain and Other Real-World Stuff
Want your site to live at `yourname.com` instead of `yourusername.github.io`? You'll need a domain. Buy one from Namecheap, Google Domains, or whoever. They're usually $10-15 per year. Then go to your GitHub repository Settings → Pages → Custom Domain. Enter your domain. GitHub will ask you to verify it by adding DNS records to your domain registrar. This part isn't intuitive, but it's a one-time setup. Follow GitHub's instructions exactly. Seriously. Once it's set up, GitHub automatically provisions an SSL certificate. Your site is HTTPS. That's genuinely nice.| Option | Best For | Time to Live | Learning Curve |
|---|---|---|---|
| Raw HTML/CSS | Complete control, small sites | 30 mins–2 hours | Moderate (if you know HTML/CSS) |
| Jekyll | Blogs, documentation | 1–3 hours | Steep (Ruby, YAML, Liquid) |
| Hugo | Fast, content-heavy sites | 2–4 hours | Moderate (YAML, themes) |
| HTML Template | Quick portfolio or landing page | 15–30 mins | Low (just customize) |
| React + Build | Interactive projects, portfolio | 1–2 hours | High (JavaScript ecosystem) |
Pro Tip: If you're using a custom domain, remember that DNS propagation takes time. Up to 48 hours in theory. Usually 10 minutes. Don't panic if it doesn't work immediately. Go grab a coffee, check back later.
Common issues I've hit and how to fix them:
**"My site isn't showing up."** Check the Pages section in Settings. Is there a build error? Look at the error message. Usually it's a YAML syntax error or a bad theme name. Copy the error into Google. Someone has solved it.
**"My CSS isn't loading."** Make sure your HTML is referencing the correct file path. If you have folders, the path matters. `` works if `styles.css` is in the root. If it's in a `css` folder, it should be `href="css/styles.css"`.
**"It works locally but not on GitHub."** This happens with Jekyll and paths. GitHub Pages runs from a subdirectory by default. Use relative paths, not absolute paths. Avoid hardcoded URLs starting with `/`.
My Take
GitHub Pages solved a real problem for me: I wanted to host a portfolio without paying money or dealing with a hosting company's terrible control panel. GitHub Pages delivered on both counts. But I'll be honest—it's not for everyone. If you're uncomfortable with Git, or if you need a database, or if you want something you can update via a web interface without touching code, this isn't it. Wix or Squarespace might frustrate you less. That said, if you're a developer (even a junior one), or a student learning to code, or someone who appreciates having full control and understanding how things work—this is genuinely hard to beat. It's free. It integrates with your workflow. Your site is version-controlled. You can deploy with a single Git command. The performance is solid because GitHub uses a CDN. What surprised me most: how stable it is. I've never had downtime. Build failures, sure. Occasionally I push something broken. But the actual GitHub Pages infrastructure? Rock solid. Who is this actually for? Developers, technical professionals, students, and anyone building a portfolio or blog who already uses GitHub. If you're not already comfortable with Git, you'll spend your first few hours frustrated. But once it clicks, you'll wonder why everyone doesn't do this.Verdict
GitHub Pages is worth the learning curve if you're technical enough to reach for it. It's genuinely free, genuinely reliable, and genuinely gives you control. Start with raw HTML if you're new to it. Don't overcomplicate it with Jekyll or Hugo until you need them. If you're not comfortable with Git yet? Learn it. This is a good reason to.Published by Dattatray Dagale • 05 September 2026
0 Comments