How to Enable GitHub Pages in Repository Settings

By -

What’s the Proper Way to Enable GitHub Pages in Repository Settings?

If you’ve just created a new repository and you're ready to publish your website using GitHub Pages, you may be unsure how to activate the Pages functionality correctly. GitHub Pages offers a free and fast way to serve static websites directly from a GitHub repository, but many beginners overlook how important the initial setup in the repository settings is.

This guide walks you through enabling GitHub Pages step by step, highlights common pitfalls, and shows you how to configure your site for Jekyll compatibility. Whether you’re hosting a blog, a documentation site, or a personal portfolio, understanding this setup ensures your site gets published properly and remains maintainable long-term.

Why Is It Important to Configure GitHub Pages from Settings?

Enabling GitHub Pages from the repository settings does more than just flip a switch. It connects your chosen branch and directory to GitHub’s static site server. If misconfigured, your site may not load, or it might display a 404 error. Additionally, if you're using Jekyll, the right configuration determines whether your site renders correctly with themes, layouts, and data files.

What Do You Need Before Activating GitHub Pages?

Before you enable GitHub Pages, make sure you have:

  • A GitHub account with at least one repository created
  • A branch that contains your site files (usually main or gh-pages)
  • A valid static site structure (HTML, CSS, or a Jekyll site)
  • Jekyll users: a _config.yml file and possibly a _posts or _site directory, depending on your workflow

With these in place, you’re ready to proceed to the actual setup.

How Do You Enable GitHub Pages in Repository Settings?

Here is a step-by-step method to enable GitHub Pages from your repository settings:

1. Open the Repository on GitHub

Log in to GitHub, go to your repository, and make sure you’re on the correct branch. Click the Settings tab located near the top of the page.

2. Scroll to the Pages Section

In the repository settings sidebar, look for the Pages option (it may appear under “Code and automation”). Click it to open the GitHub Pages configuration screen.

3. Choose the Source Branch

You’ll see a “Source” dropdown menu. Select the branch you want to publish from, such as main or gh-pages. Then, select the folder:

  • If you're using raw HTML or Jekyll from the root, choose /(root)
  • If your built site is inside a /docs or _site folder, choose that folder

4. Save Your Settings

After choosing the source, click the Save button. GitHub will now attempt to publish your site. You’ll be shown the public URL where your site will be hosted, typically:

https://your-username.github.io/your-repository-name/

What Happens Behind the Scenes After You Enable It?

Once you configure GitHub Pages, GitHub runs a deployment process behind the scenes. For Jekyll sites, it also builds the site using Jekyll (unless you disable Jekyll by adding a .nojekyll file).

The deployment may take up to a minute. Once done, the site will be available at the public URL provided. Any change you make to your selected branch will automatically trigger a new deployment.

Does This Work for Custom Domains?

Yes, once GitHub Pages is active, you can assign a custom domain. Just add a CNAME file to your repository or configure it through the Pages settings. Don’t forget to set up DNS records pointing to GitHub Pages’ IPs.

Why Might Your GitHub Pages Site Not Show Up?

Here are common issues users face after enabling GitHub Pages:

  • Wrong branch or folder selected: Make sure you selected the correct branch and folder from settings.
  • Missing index.html: Every GitHub Pages site must have an index.html in the root or specified folder.
  • Empty branch: If your branch doesn’t contain site files, nothing will show.
  • Jekyll errors: If you're using Jekyll, syntax errors in templates or front matter can break the build.

Can You Use GitHub Pages Without Jekyll?

Yes. Although GitHub Pages has built-in support for Jekyll, it works with any static site—such as sites built with Hugo, Eleventy, or plain HTML. To disable Jekyll processing, create an empty file named .nojekyll in your root directory.

How Do You Know Your GitHub Pages Site Is Live?

After enabling GitHub Pages, GitHub displays a banner on the Pages settings page with the link to your live site. You can also go directly to:

https://your-username.github.io/your-repo-name/

If it's not live within a few minutes, recheck your settings or try pushing a small change (like editing the README) to trigger a redeployment.

What If You Want to Use the gh-pages Branch Instead?

Some developers prefer using a dedicated gh-pages branch to keep code and site separate. In that case:

  • Create a gh-pages branch in your repository
  • Add your built site files to that branch
  • Go to Settings → Pages and choose gh-pages as the source

This approach is common for frontend frameworks that generate a static dist or build folder, like React or Vue.

What If You Want to Host a Jekyll Blog?

If your repository contains a Jekyll blog, just ensure the structure includes:

  • A _config.yml file
  • A _posts directory with at least one post
  • A _layouts and _includes folder (optional, but recommended)

GitHub Pages automatically builds Jekyll sites unless .nojekyll is present.

What Should You Do After Enabling GitHub Pages?

Here are best practices to follow once your site is live:

  • Test your site on desktop and mobile browsers
  • Set up a robots.txt if you want to control search engine indexing
  • Add a sitemap for SEO using a plugin or manually
  • Connect your site to Google Search Console

Final Thoughts

Enabling GitHub Pages through repository settings is a simple but vital step in launching your static site. Whether you're using Jekyll or not, understanding how to configure your branch, folder, and supporting files ensures a smooth deployment experience. Once you’ve completed the setup, you can start iterating on your design, content, and SEO without worrying about your hosting infrastructure.

GitHub Pages is ideal for personal sites, documentation, and even small business pages. With the correct setup, it becomes a powerful free platform to share your work with the world.