J. Rogers, SE Ohio
The Concept
GitHub Pages has a specific hierarchy:
The Root: https://yourname.github.io/ (Your Hub)
The Projects: https://yourname.github.io/project-name/ (Your Apps)
By creating one specific repository, you can create a central "Lobby" that links to all your other documentation sites.
Step 1: Create the Special Repository
Log into GitHub.
Click the + icon in the top right and select New repository.
Repository name: This is the most important step. You must name it exactly:
yourusername.github.io
(Replace
Make it Public.
Check Add a README file (optional, but helpful).
Click Create repository.
Step 2: Create the Index Page
Inside your new repository, click Add file > Create new file.
Name the file: index.html
Paste in this generic, professional template. It handles mobile screens and looks modern automatically.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Documentation Hub</title>
<style>
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.6; color: #333; background: #f9f9f9; margin: 0; padding: 20px; }
.container { max-width: 900px; margin: 60px auto; }
header { text-align: center; margin-bottom: 60px; }
h1 { font-size: 2.5em; margin-bottom: 10px; color: #2d3436; }
p.subtitle { color: #636e72; font-size: 1.2em; }
.grid { display: grid; grid-template-columns: 1fr; gap: 40px; }
@media (min-width: 768px) { .grid { grid-template-columns: 1fr 1fr; } }
.card {
background: white;
padding: 30px;
border-radius: 10px;
box-shadow: 0 4px 6px rgba(0,0,0,0.05);
border-top: 5px solid #0984e3;
transition: transform 0.2s;
display: flex;
flex-direction: column;
}
.card:hover { transform: translateY(-5px); }
h2 { margin-top: 0; color: #2d3436; }
p { color: #636e72; flex-grow: 1; }
a.btn {
display: inline-block;
margin-top: 20px;
padding: 10px 20px;
background: #dfe6e9;
color: #2d3436;
text-decoration: none;
border-radius: 5px;
font-weight: 600;
text-align: center;
}
a.btn:hover { background: #b2bec3; }
footer { text-align: center; margin-top: 60px; color: #b2bec3; font-size: 0.9em; }
footer a { color: #636e72; }
</style>
</head>
<body>
<div class="container">
<header>
<h1>My Projects</h1>
<p class="subtitle">A collection of documentation and learning resources.</p>
</header>
<div class="grid">
<div class="card">
<h2>Regex Learning</h2>
<p>Interactive visualization of Regular Expressions. View patterns, test inputs, and match results side-by-side.</p>
<a href="/regex_learning/" class="btn">View Project →</a>
</div>
<div class="card" style="border-top-color: #00b894;">
<h2>SQL Master Course</h2>
<p>Story-driven SQL tutorial. Builds a persistent Bookstore database in the browser using Python and SQLite.</p>
<a href="/sql_master_course/" class="btn">View Project →</a>
</div>
<div class="card" style="border-top-color: #6c5ce7;">
<h2>Future Project</h2>
<p>Description of your next tool or documentation site goes here.</p>
<a href="#" class="btn">Coming Soon</a>
</div>
</div>
<footer>
<a href="https://github.com/YOUR_USERNAME">View my GitHub Profile</a>
</footer>
</div>
</body>
</html>
Step 3: Publish
Scroll to the bottom of the edit page.
Click Commit changes.
Go to Settings (top tabs of the repo).
Click Pages (in the left sidebar).
Under Build and deployment, ensure Source is "Deploy from a branch".
Ensure Branch is set to main (or master) and folder is / (root).
Click Save.
Step 4: The Magic Linking
Wait about 60 seconds. Then visit:
https://yourusername.github.io/
You will see your Hub.
Why the links work:
In the code above, the links look like this: href="/regex_learning/".
Because this file is at the root, the browser interprets that link as https://yourusername.github.io/regex_learning/.
As long as you have a separate repository named regex_learning that is also published to GitHub Pages, the link will work instantly.
Step 5: Preparing Your Other Projects
For your "Spoke" projects (like regex_learning or sql_master_course) to work, they must output their HTML to a specific folder so GitHub can serve them.
Configure Output: Ensure your Python generator script saves files to a folder named docs (not html_output).
Change in script: self.out_dir = self.base / "docs"
Generate: Run your script (python generate.py). You should see a docs folder appear with index.html inside it.
Push: Commit and push these changes to GitHub.
Configure GitHub:
Go to the Project Repository's Settings > Pages.
Under Branch, select main.
Crucial Step: Select the /docs folder (instead of root) in the dropdown next to the branch.
Click Save.
Step 6: Adding a New Project Card
When you build a new tool, simply edit the index.html file in your Hub repository (yourname.github.io).
Open index.html and find the <div class="grid">.
Copy and paste this block inside the grid:
<div class="card" style="border-top-color: #e17055;">
<h2>Project Name</h2>
<p>Write a 1-2 sentence description of what this tool teaches.</p>
<a href="/repository-name/" class="btn">View Project →</a>
</div>
Commit the change. Your Hub will update automatically.
Troubleshooting
404 Error? It can take 1-2 minutes for GitHub to build the site the first time. Refresh the page.
Links don't work?
Make sure your project repositories (e.g., regex_learning) have GitHub Pages enabled in their settings.
Make sure the href in your HTML matches the repository name exactly (case-sensitive).
