Github Pages – AI Conversation

In 2026, the best practice for managing GitHub Pages is actually a third option that avoids branch-switching entirely: GitHub Actions.

However, if you are choosing between the traditional branch-based methods, here is the breakdown of which is better for your workflow:

1. The Modern Way: GitHub Actions (Recommended)

Instead of tying your site to a specific branch (like gh-pages), you configure GitHub Pages to build from a GitHub Action.

• How it works: You keep only one branch (main). Whenever you push code, an Action automatically builds your site (Jekyll, Hugo, React, etc.) and deploys the output to a “hidden” environment.
• Why it’s better: No “messy” deployment branches, no sync issues, and you can run tests/linting before the site actually updates.
• Setup: In Settings > Pages, under “Build and deployment,” change the Source to “GitHub Actions.”

2. The “Single Branch” Strategy (Better for simple sites)

If you aren’t using a complex build tool (just HTML/CSS), keep everything on main.

• Pros: Simplest workflow. What you see on main is exactly what is live.
• Cons: If you are working on a large update that takes days, your “work in progress” will be live on the site as soon as you push to main.
• Best for: Small sites, portfolios, or sites where you don’t mind “live” development.

3. The “Two Branch” Strategy (Merge into gh-pages)

You work on main and merge into a gh-pages branch only when ready to deploy.

• Pros: Acts as a “Production” vs “Development” environment. You can break things on main without taking down the live site.
• Cons: High maintenance. You have to remember to merge every time you want an update. It’s easy for branches to drift apart.
• Best for: Teams or projects where you need a stable “Production” version at all times.

Comparison Summary for 2026

Recommendation for remote-tech.us:

Since you are already setting up professional DNS via Cloudflare, move to GitHub Actions.

1. Keep a single main branch.
2. Use the official GitHub Pages deployment action.
3. This allows you to work on your site locally, and only have it go live when you git push.

Yes, exactly. In 2026, switching to GitHub Actions allows you to keep a single main branch for your source code while the deployment happens behind the scenes. 

How it works with GitHub Actions

1. Single Source of Truth: You keep your source files (HTML, Hugo templates, or Node scripts) on your main branch.
2. The Trigger: Every time you git push to main, a GitHub Actions workflow is triggered.
3. The Build: The Action spins up a temporary virtual machine, installs your tools (like Hugo or Node), runs your build command (e.g., hugo or npm run build), and captures the resulting static HTML/CSS.
4. The Deployment: Instead of pushing those built files to a gh-pages branch, the Action “uploads an artifact” directly to GitHub’s internal Pages server. 

Managing your different tech stacks

GitHub Actions is the “universal glue” that lets you handle all your branches/ideas in one place: 

• For Hugo: Use the official Hugo setup action. It builds your content/ folder into a public/ folder in seconds.
• For NodeJS: Note that GitHub Pages cannot run a Node server (no dynamic backend). However, you can use Node to build a static site (like a React or Vue app). The Action runs npm install and npm run build, then deploys the generated dist/ or build/ folder.
• For Plain HTML: The Action simply takes your root folder and deploys it as-is. 

How to Switch

1. In GitHub Settings: Go to Settings > Pages. Under Build and deployment, change the Source dropdown from “Deploy from a branch” to “GitHub Actions”.
2. Add a Workflow File: GitHub will suggest templates. If you choose Hugo, it will create a .github/workflows/hugo.yml file in your repo.
3. Clean Up: Once this is working, you can safely delete the gh-pages branch. It is no longer needed, keeping your repository much cleaner. 

Why this is better for you right now:

Since you are experimenting with different branches (HTML, Node, Hugo), GitHub Actions lets you standardize. You can eventually merge your favorite parts into main and just update your .yml workflow file to tell GitHub how to build the final version of remote-tech.us. 

GitHub Pages does not natively support multiple custom subdomains for a single repository. Each repository is limited to one custom domain or subdomain. 

However, you can achieve your goal using one of the following methods:

1. Separate Repositories (The “Standard” Way)

Create a new repository for each subdomain (e.g., remote-tech-site1, remote-tech-site2). 

• Enable GitHub Pages on each repository.
• In the Settings > Pages for each repo, assign the specific subdomain (e.g., site1.remote-tech.us).
• DNS: Point a CNAME for site1 and site2 to your main remote-tech-us.github.io address in Cloudflare. 

2. Subdirectories (Single Repository, Single Domain) 

Host all sites in one repository but serve them from subfolders rather than subdomains. 

• URL Structure: remote-tech.us/site1, remote-tech.us/site2.
• Setup: Organize your repo with folders named site1/ and site2/. GitHub will automatically serve their content at those paths. 

3. Subdirectories with Cloudflare Workers (Advanced)

If you must have subdomains (e.g., site1.remote-tech.us) while keeping everything in one repository, you can use a Cloudflare Worker as a reverse proxy. 

• The Worker intercepts requests for site1.remote-tech.us and internally fetches content from remote-tech.us/site1.
• This keeps the visitor’s URL as the subdomain while your repository remains a single project. 

4. Separate Branches (Not Recommended)

You can technically use different branches for different sites, but you cannot map a separate subdomain to each branch within the same repository. You would still be limited to one custom domain for the entire repo. 

If you use Option #2 with a single repository and a GitHub Action, you can configure the build process so that your main site is at the root and your Hugo site sits in a clean subdirectory like https://remote-tech.us or https://remote-tech.us.

How your URLs would look:

• Main Site (HTML/Dashboard): https://remote-tech.us
• Hugo Site: https://remote-tech.us (The /content/ folder and index.html are hidden/rendered away by Hugo).

How to structure your Repository:

To make this work in one repo, you would organize your files like this:

.
├── index.html          <-- Your main dashboard
├── assets/             <-- Dashboard CSS/JS
└── my-hugo-project/    <-- The entire Hugo folder
    ├── config.toml
    ├── content/
    └── themes/

The “Magic” of the GitHub Action (2026 Strategy)

Because you have two different technologies (Plain HTML and Hugo), a standard “push to branch” won’t work easily. You need a GitHub Action to “stitch” them together:

1. Step 1: The Action copies your root index.html to a temporary deployment/ folder.
2. Step 2: The Action runs the Hugo build command, but tells it to output the files into deployment/hugo/.
3. Step 3: The Action uploads the entire deployment/ folder to GitHub Pages.

A Note on Hugo’s baseURL

If you go this route, you must update your Hugo configuration file (config.toml or hugo.yaml):

• baseURL: "https://remote-tech.us"

If you don’t set the baseURL correctly, your Hugo site’s CSS and images will break because the site will look for them at the root (/) instead of inside the /hugo/ subfolder.

Is there a downside?

The only downside to Option #2 is Build Time. Every time you fix a typo on your main dashboard, the GitHub Action has to rebuild the entire Hugo site as well. For a small site, this takes less than a minute, but it is something to keep in mind as the site grows.

In 2026, the choice between separate repositories and a single repository depends on whether you want distinct subdomains (e.g., hugo.remote-tech.us) or a single domain with subdirectories (e.g., remote-tech.us/hugo). 

Option #1: Separate Repositories (The “Subdomain” Way)

GitHub Pages only allows one custom domain per repository. To host multiple sites on separate subdomains, you must create a separate repository for each site. 

• Setup:
  1. Create a new repository (e.g., remote-tech-hugo).
  2. Enable GitHub Pages in that repo’s settings.
  3. Enter the specific subdomain (e.g., hugo.remote-tech.us) in the Custom domain field.
  4. DNS: In Cloudflare, add a CNAME record for hugo pointing to your main GitHub user site (e.g., remote-tech-us.github.io).
• Pros:
  • True Isolation: Changes or build failures in one site cannot break the other.
  • Distinct URLs: You get professional subdomains like site1.remote-tech.us.
  • Permissions: You can grant different people access to specific sites if needed.
• Cons:
  • Management Overhead: You have to manage multiple repos, SSH keys, and local clones.
  • Duplicate Work: Shared components (like a navigation bar or CSS) must be copied or managed via submodules. 

Option #2: Subdirectories (The “Single Repo” Way)

You keep everything in one repository and host secondary sites in folders. 

• Setup:
  1. Place your main site in the root and secondary sites in folders (e.g., /hugo/).
  2. GitHub serves these at remote-tech.us/ and remote-tech.us/hugo/.
  3. Action Build: Use a GitHub Action to build the Hugo project into that specific subfolder during deployment.
• Pros:
  • Centralized Control: All your code is in one place, making global updates easier.
  • Simpler DNS: You only need to configure and secure one domain (remote-tech.us).
  • Atomic Commits: You can update the main landing page and the Hugo site in a single commit.
• Cons:
  • No Subdomains: You are forced to use ://domain.com instead of sub.domain.com.
  • Build Bottleneck: A change to a single line of HTML in the root forces the entire Hugo site to rebuild every time you push.
  • Pathing Issues: You must carefully set Hugo’s baseURL to include the subfolder, or images and styles will break. 

Summary Comparison Table (2026)

Recommendation: If you want a professional brand with distinct “apps” or “sections,” use Option #1. If you just want to host some experimental projects under your main brand, use Option #2.

Yes, for a subdomain in Option #1 (e.g., hugo.remote-tech.us), you only need a single CNAME record. You do not need to add the A or AAAA records to the subdomain’s DNS entry. 

How to set it up in Cloudflare:

1. Type: CNAME
2. Name: hugo (or your desired subdomain)
3. Target: remote-tech-us.github.io
4. Proxy Status: Set to Grey Cloud (DNS Only) initially to ensure GitHub can verify the domain and issue the SSL certificate. 

Why you don’t need A/AAAA records:

• Apex vs. Subdomain: Standard DNS rules require A records for an apex domain (root), but subdomains are better handled via CNAME.
• Maintenance: By using a CNAME pointing to remote-tech-us.github.io, you don’t have to worry if GitHub ever changes its underlying IP addresses. The CNAME will always resolve to the correct server. 

Important: Keep your Apex records

Don’t delete the A and AAAA records you already set up for remote-tech.us. They are still required to keep your main landing page working. The new CNAME for the subdomain will live alongside them as a separate entry in your Cloudflare DNS table. 

Final Steps for Option #1:

• In your new Hugo repository on GitHub, go to Settings > Pages.
• In the Custom domain field, enter hugo.remote-tech.us.
• Wait for the DNS check to pass and the “Enforce HTTPS” checkbox to become available. 

Yes, in 2026, you can host your Hugo site in a completely different GitHub organization while keeping your main landing page and apex domain (remote-tech.us) under your current account. 

However, there is a critical security requirement you must fulfill to make this work: Verification across organizations.

1. The Verification Requirement

When you verify a custom domain (like remote-tech.us) for a specific GitHub organization, GitHub restricts that domain and all of its immediate subdomains to repositories owned only by that organization. 

To allow a different organization to use hugo.remote-tech.us:

• If you verified the domain in Org A: Org B will be blocked from using any *.remote-tech.us subdomain.
• The Fix: You must also verify the domain in the second organization’s settings. This involves adding a unique DNS TXT record provided by the second organization to your Cloudflare DNS table. 

2. DNS Setup for the Second Org

Once the second organization is verified, you only need to add the single CNAME for the subdomain: 

• Type: CNAME
• Name: hugo
• Target: [other-org-name].github.io
• Proxy Status: DNS Only (Grey Cloud) 

3. Summary of Configuration

• Your Main Account: Keeps the 4 A records and 4 AAAA records for remote-tech.us.
• The Second Organization: Hosts the Hugo repository. Its “Pages” settings will have hugo.remote-tech.us as the custom domain.
• Cloudflare: Will contain your existing records plus a new CNAME pointing to the second organization’s GitHub URL and a TXT record for verification. 

Pros & Cons of this Multi-Org Approach

• Pros: Total isolation of projects and billing; easier to collaborate with different teams on the Hugo site without giving them access to your main landing page.
• Cons: You must manage DNS verification for two different GitHub entities; SSL certificate generation for the subdomain might take slightly longer during the first-time handoff between accounts. 

That is a wise choice for 2026. Keeping everything under one organization or account significantly simplifies your workflow and avoids the overhead of managing multiple domain verification TXT records.

Summary of your Final Configuration

Now that you are staying in one organization, here is your checklist for Option #1 (Subdomains):

1. Repository 1 (main-site):
   • Content: Your landing page/dashboard.
   • GitHub Pages Settings: Custom domain set to remote-tech.us.
   • Cloudflare DNS: Keep those 4 A records and 4 AAAA records pointing to GitHub’s IPs (Grey Cloud).
2. Repository 2 (hugo-site):
   • Content: Your Hugo source code.
   • GitHub Pages Settings: Custom domain set to hugo.remote-tech.us.
   • Cloudflare DNS: Add one CNAME record:
     • Name: hugo
     • Target: remote-tech-us.github.io
     • Status: Grey Cloud.
3. Deployment:
   • Since you are using Hugo, use the GitHub Actions deployment method in Repository 2. It will build your site and push it to the hugo.remote-tech.us subdomain automatically.

Why this works so well:

• Security: GitHub will automatically issue separate SSL certificates for remote-tech.us and hugo.remote-tech.us.
• Performance: Both sites will benefit from GitHub’s global CDN (Fastly) even though Cloudflare is set to “DNS Only.”
• Scalability: If you decide to add blog.remote-tech.us or docs.remote-tech.us later, you just repeat the steps for Repository 2 without ever touching your main landing page code.

Your dig commands from earlier proved that you have a solid handle on how the traffic is moving. You’re all set!

To move to a multi-repo architecture in 2026, you should extract your specialized subdirectories into their own independent repositories. This prevents one site’s build from interfering with another and allows for cleaner URLs (e.g., gatsby.remote-tech.us vs. remote-tech.us/gatsby-starter-ghost). 

Suggested Multi-Repo Path

Based on your current tree, you should split your project into three distinct repositories:

1. remote-tech-us.github.io (Main Repo): Keep your root index.html, style.css, Components.js, and the img/ folder here. This serves as your primary landing page at https://remote-tech.us.
2. remote-tech-gatsby (New Repo): Move the contents of gatsby-starter-ghost/ to the root of this new repository.
3. remote-tech-vite (New Repo): Move the contents of react-vite/ to the root of this new repository.

Step-by-Step Extraction (Preserving History)

To split these folders into new repos while keeping your commit history, use git filter-repo (the 2026 recommended tool) or git subtree. 

1. Extract the Gatsby Site

# 1. Create a fresh clone for safety
git clone 
 gatsby-split
cd gatsby-split

# 2. Extract the folder and make it the new root
git filter-repo --subdirectory-filter gatsby-starter-ghost/

# 3. Push to its new home
git remote add origin 

# 4. Push to remote
git push -u origin main

2. Extract the React Vite Site

Repeat the process for react-vite/ into a new repository named remote-tech-vite.

3. Cleanup the Main Repo

In your original remote-tech-us.github.io repository, you can now safely delete the subdirectories to keep it lightweight:

git rm -r gatsby-starter-ghost/ react-vite/ react-mui/
git commit -m "Cleanup: Move specialized projects to separate repositories"
git push

Post-Split DNS & Deployment

Once split, configure each new site to have its own subdomain: 

• Main Site: remote-tech.us (Keep your current A/AAAA records).
• Gatsby Site: gatsby.remote-tech.us (Add a CNAME in Cloudflare pointing to remote-tech-us.github.io).
• Vite Site: app.remote-tech.us (Add a CNAME in Cloudflare pointing to remote-tech-us.github.io). 

Why this is better for 2026:

• Faster Builds: Updating your main index.html won’t trigger a 2-minute Gatsby build.
• Cleaner Root: You won’t have conflicting package.json or node_modules in the same repo.
• Isolation: If your Gatsby site has a build error, your main remote-tech.us landing page stays online. 

In 2026, the short answer is yes. Since both Gatsby and Vite require a “build step” (converting your React code into static HTML/JS/CSS), they cannot be deployed by GitHub’s default “Deploy from a branch” setting alone. 

Here is how you handle the workflows for each of your new repositories:

1. The Main Landing Page (remote-tech-us.github.io)

• Workflow needed? No (unless you want one).
• Why: Since this repo contains just plain index.html and style.css, you can go to Settings > Pages and keep the source as “Deploy from a branch”. GitHub will automatically run its own internal action to serve your files. 

2. The Gatsby Site (remote-tech-gatsby)

• Workflow needed? Yes.
• The File: Create .github/workflows/deploy.yml.
• What it does: It must run npm install and gatsby build.
• Settings: In GitHub Settings > Pages, you must switch the Source to “GitHub Actions”.
• Pro Tip: GitHub provides a “Gatsby” starter template under the Actions tab that writes the yml file for you. 

3. The Vite React Site (remote-tech-vite)

• Workflow needed? Yes.
• The File: Create .github/workflows/deploy.yml.
• What it does: It runs npm install and npm run build.
• Crucial Step: You must ensure the workflow uploads the dist/ folder (the standard Vite output) to GitHub Pages.
• Settings: Switch the Source to “GitHub Actions” in the repository settings. 

Summary of the “Single-Branch” Workflow

By using these yml files in your new repos, you achieve the clean 2026 setup you wanted:

1. Work on main branch: You never have to manually touch a gh-pages branch again.
2. Push to Deploy: Simply git push origin main, and the Action builds and deploys the site to your subdomain automatically.
3. Permissions: Make sure your yml files include the necessary permissions (pages: write, id-token: write) so the Action has authority to publish to your domain. 

In 2026, git filter-repo is the standard tool recommended by Git maintainers for rewriting repository history. While git clone copies the current state and all history as-is, git filter-repo allows you to edit the past. 

What it actually does

Think of it as a “surgical filter” for your repository’s timeline. When you run git filter-repo --subdirectory-filter gatsby-starter-ghost/, it scans every single commit ever made in your repo and does the following: 

• Deletes everything else: It discards any files or folders that were not inside gatsby-starter-ghost/ from every historical commit.
• Promotes the folder: It moves the contents of gatsby-starter-ghost/ up to the root level. For example, gatsby-starter-ghost/package.json becomes just package.json in every commit in the new history.
• Prunes empty commits: If a past commit only changed files you’ve now deleted, that commit is removed entirely to keep the history clean.
• Rewrites IDs: Because the content of the commits has changed, every commit gets a brand new SHA-1 hash (ID). 

Why you use it instead of just copying files

If you just copy the files to a new repo, you lose all the “Why” behind your code—the commit messages, dates, and the evolution of the project. git filter-repo ensures that when you look at your new remote-tech-gatsby repo, the git log still shows exactly who changed what and when, dating back to the very first day you started that branch. 

Installation for 2026

Since it is a Python-based tool, you may need to install it if it’s not already on your system: 

• macOS: brew install git-filter-repo
• Linux (Ubuntu): sudo apt install git-filter-repo or pip install git-filter-repo
• Windows: pip install git-filter-repo 

Safety Warning

This tool is destructive by design. It refuses to run unless it detects you are in a fresh clone of a repository. This is to prevent you from accidentally wiping out the local-only work in your main development folder. Always use a temporary folder for the split. 

Before you start the “big split,” here is one final 2026 checklist to ensure everything goes smoothly:

1. Backup: Keep your original remote-tech-us.github.io folder untouched. Only run the filter-repo commands inside the new temporary clones.
2. CNAME Files: After you split the repos, ensure each one has the correct CNAME file in the root (e.g., the Gatsby repo should have a CNAME file containing gatsby.remote-tech.us).
3. Vite/Gatsby Base Paths: If you decide to use subfolders (Option #2) instead of subdomains (Option #1), remember to update the base in vite.config.js or pathPrefix in Gatsby. (If you use subdomains, you can usually leave these as /).
4. Action Permissions: If your GitHub Actions fail on the first run, check Settings > Actions > General and ensure “Workflow permissions” are set to Read and write permissions.

You’ve built a professional-grade infrastructure for your project. Enjoy the clean, automated workflow! Feel free to reach out if you hit any snags with the yml configurations. Happy coding!

In 2026, the best way to handle this is to treat your current repository as a “template” and the new folders as independent workspaces. The renaming happens at the folder level on your computer and the repository level on GitHub. 

Here is exactly when and where the “renaming” occurs during the process:

1. The Local Rename (On your Computer)

When you clone your repository, you don’t have to accept the default folder name. You can rename it immediately during the clone command or right after. 

• Option A (At Clone): Specify the new folder name at the end of the command.
  git clone https://github.com remote-tech-gatsby
• Option B (After Clone): Rename the folder using standard terminal commands.
  mv remote-tech-us.github.io remote-tech-gatsby

2. The git filter-repo Stage

At this point, you are inside a folder named remote-tech-gatsby, but the internal Git history still thinks it is the original repo. When you run:
git filter-repo --subdirectory-filter gatsby-starter-ghost/
The tool scrubs the history. It doesn’t “rename” the repo itself, but it deletes every file except those in that folder and moves them to the root. 

3. The GitHub Rename (On the Cloud)

Since you are moving this content to a new home, you must create a new repository on GitHub with the name remote-tech-gatsby. 

1. Go to GitHub and create a new, empty repository named remote-tech-gatsby.
2. In your local terminal (inside the filtered remote-tech-gatsby folder), tell Git where its new home is:
   git remote add origin https://github.com
3. Push the code:
   git push -u origin main 

Summary Table: Where is the name changed?

Pro-Tip for 2026: If you already created the repo on GitHub with the “wrong” name, you can change it anytime in Settings > General > Repository Name. GitHub is very good at redirecting old URLs to new ones automatically.