Hey guys! Ever wanted to deploy just a specific subdirectory of your GitHub repository to GitHub Pages? It's a pretty common scenario, especially when you have multiple projects within the same repo, or you only want to showcase a specific part of your code. Don't worry, it's totally doable, and I'm here to walk you through it step by step. Let's dive in!

Why Deploy a Subdirectory?

Before we get into the "how," let's quickly touch on the "why." Deploying a subdirectory can be super useful in various situations:

• Multiple Projects in One Repo: Imagine you have a repository with several small projects, each in its own folder. You might want to host each project on its own GitHub Pages site.
• Focusing on a Specific Feature: Maybe you've built a really cool feature within a larger project and want to showcase it independently.
• Keeping Things Organized: Sometimes, you just want to keep your main project clean and deploy a specific part of it separately.

Whatever your reason, deploying a subdirectory to GitHub Pages is a neat trick to have up your sleeve.

Step-by-Step Guide

Okay, let's get down to business. Here’s how you can deploy a subdirectory to GitHub Pages:

Step 1: Create Your Repository and Subdirectory

First things first, you need a GitHub repository with the subdirectory you want to deploy. If you already have this, great! If not, create a new repository and add your project to a subdirectory within it. For example, let's say you have a directory named my-project that you want to deploy.

Step 2: Navigate to Your Subdirectory

Open your terminal or command prompt and navigate to the root of your repository. Then, change your current directory to the subdirectory you want to deploy. For example:

cd my-project

Step 3: Initialize a New Git Repository (If Necessary)

In some cases, especially if your subdirectory wasn't initially part of the main repository's history, you might need to initialize a new Git repository inside your subdirectory. This creates a separate Git history for your subdirectory, which can be useful for deployment. To do this, run:

git init

Step 4: Create a New Orphan Branch

This is the crucial step! We're going to create a new orphan branch named gh-pages. An orphan branch is a branch that has no parent commits, meaning it's completely disconnected from the rest of your repository's history. This is perfect for deploying a subdirectory because it allows us to create a clean, independent history for our GitHub Pages site.

Run the following command:

git checkout --orphan gh-pages

This command does several things:

• git checkout: Switches your current branch.
• --orphan gh-pages: Creates a new orphan branch named gh-pages. If your project already has this branch you can create a new one like git checkout --orphan new-gh-pages.

Step 5: Add and Commit Your Files

Now, add all the files in your subdirectory to the staging area and commit them. This will create the initial commit on your gh-pages branch.

git add .
git commit -m "Initial commit for gh-pages"

Step 6: Push to the gh-pages Branch

Push your gh-pages branch to your GitHub repository. This will make your subdirectory's content available on GitHub Pages.

git push origin gh-pages

Step 7: Configure GitHub Pages

Go to your GitHub repository on the GitHub website. Navigate to Settings > Pages. Under the Source section, select the gh-pages branch (or whatever you named your orphan branch) and save. If you initialized a new git repository you must chose the /root option.

GitHub Pages will now build and deploy your subdirectory's content. This might take a few minutes, so be patient!

Step 8: Access Your GitHub Pages Site

Once the deployment is complete, you can access your GitHub Pages site at https://<your-username>.github.io/<your-repository-name>. If you're using a custom domain, you'll need to configure it in the GitHub Pages settings.

Dealing with Assets and Links

One thing to keep in mind when deploying a subdirectory is how your assets (like images, CSS files, and JavaScript files) and links are handled. Since your site is now hosted in a subdirectory, you might need to adjust the paths to these assets and links to ensure they work correctly.

Relative Paths

The best way to handle assets and links is to use relative paths. Relative paths are paths that are relative to the current page. For example, if you have an image in the images folder within your subdirectory, you can link to it like this:

<img src="images/my-image.jpg" alt="My Image">

This will work regardless of whether your site is hosted in a subdirectory or at the root of your domain.

Base URL

In some cases, you might need to set a base URL for your site. This is especially useful if you're using a static site generator like Jekyll or Hugo. The base URL tells your site where it's being hosted, so it can correctly resolve assets and links.

For example, in Jekyll, you can set the baseurl option in your _config.yml file:

baseurl: /my-project

This tells Jekyll that your site is being hosted in the my-project subdirectory.

Troubleshooting

Sometimes, things don't go quite as planned. Here are a few common issues you might encounter when deploying a subdirectory to GitHub Pages, along with some potential solutions:

404 Errors

If you're getting 404 errors, it usually means that your assets or links are not being resolved correctly. Double-check your paths and make sure they're relative to the current page. Also, make sure that your base URL is set correctly if you're using a static site generator.

Incorrectly Displayed Pages

If your pages are not displaying correctly, it could be due to caching issues. Try clearing your browser's cache and refreshing the page. You can also try using a different browser to see if the issue persists.

Deployment Delays

Sometimes, it can take a while for GitHub Pages to deploy your site. This is especially true if you've made a lot of changes or if GitHub is experiencing high traffic. Be patient and wait a few minutes before checking your site again.

Alternatives

While deploying a subdirectory to GitHub Pages is a great option, there are other ways to achieve a similar result. Here are a few alternatives:

• Using a Custom Domain: If you have a custom domain, you can create subdomains for each of your projects. This allows you to host each project on its own subdomain, which can be a cleaner and more professional solution.
• Using a Hosting Provider: There are many hosting providers that offer easy deployment and hosting for static sites. Services like Netlify and Vercel are great options.
• Using a Static Site Generator: Static site generators like Jekyll, Hugo, and Gatsby can help you build and deploy static sites quickly and easily. They also offer features like templating, asset optimization, and content management.

Conclusion

Deploying a subdirectory to GitHub Pages is a simple and effective way to host multiple projects within the same repository or showcase a specific part of your code. By following the steps outlined in this guide, you can easily deploy your subdirectory and get your site up and running in no time. Remember to pay attention to your assets and links, and don't be afraid to experiment with different approaches. Happy deploying, and I hope this guide was helpful!