How I Built My Technical Writing Portfolio Website Using GitHub Pages
As a technical writer and software engineer, I wanted a portfolio site that showcased my skills, articles, and publications in a way that felt modern and personal. I built it with HTML + CSS, hosted it on GitHub Pages, and added extra features like animations, Google Search Console, Analytics, and a sitemap.
Here’s exactly how I built it, step-by-step — no frameworks, no CMS, just code and care.
🛠️ Tools I Used
- HTML + CSS — fully custom, no frameworks
- GitHub Pages — free, fast hosting
- Google Search Console — to help get discovered on Google
- Google Analytics (GA4) — to track visitors
- VS Code — for writing code
- A simple animated avatar PNG — for personality ✨
🧱 Step 1: Create a GitHub Pages Repo
- Go to https://github.com
Create a new repo named:yourusername.github.io
Make sure it’s public.You can either:
Clone it locally (
git clone)Or drag-and-drop files directly into GitHub’s interface
💻 Step 2: Create index.html
This is the homepage. Here's the full code I used (copy it to a file called index.html):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>Your Name | Technical Writer</title>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
<link rel="stylesheet" href="style.css">
<!-- Google Analytics (replace with your ID) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
<!-- Google Search Console verification -->
<meta name="google-site-verification" content="your-verification-code" />
<!-- Smooth scroll, link animation, fade effect -->
<style>
html {
scroll-behavior: smooth;
}
@keyframes fadeSlideUp {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
#work-section {
animation: fadeSlideUp 1.5s ease-in-out both;
}
h2 {
position: relative;
animation: slideIn 0.9s ease forwards;
opacity: 0;
}
@keyframes slideIn {
from { opacity: 0; transform: translateX(-20px); }
to { opacity: 1; transform: translateX(0); }
}
a {
color: #4dd0e1;
text-decoration: none;
position: relative;
transition: color 0.3s ease;
}
a:hover {
color: #ffffff;
}
a::after {
content: "";
position: absolute;
width: 0%;
height: 2px;
left: 0;
bottom: -4px;
background: linear-gradient(to right, #4dd0e1, #f97316);
transition: width 0.4s ease;
}
a:hover::after {
width: 100%;
}
.emoji-bg {
position: absolute;
top: 120px;
right: 30px;
font-size: 3rem;
opacity: 0.05;
z-index: 0;
pointer-events: none;
animation: float 6s ease-in-out infinite;
}
@keyframes float {
0% { transform: translateY(0px); }
50% { transform: translateY(-15px); }
100% { transform: translateY(0px); }
}
</style>
</head>
<body>
<div class="emoji-bg">🧠</div>
<nav>
<div class="logo-container">
<img src="avatar.png" alt="Logo" style="width: 60px; height: 60px; border-radius: 50%;">
<strong>Your Name</strong>
</div>
<div>
<a href="index.html">Home</a>
<a href="contact.html">Contact</a>
<a href="https://github.com/yourusername" target="_blank">GitHub</a>
</div>
</nav>
<main>
<h1>Hello, I'm [Your Name]</h1>
<p>
I’m a software engineer and technical writer with a focus on backend architecture and developer experience.
I build scalable systems and write structured documentation to make complex tools easier to use.
</p>
<h2>What I Do</h2>
<ul>
<li><strong>Technical Writing:</strong> API docs, onboarding guides, tutorials</li>
<li><strong>Software Engineering:</strong> Python, JavaScript, and backend systems</li>
<li><strong>Dev Tools:</strong> Markdown, LaTeX, Confluence, GitHub Actions</li>
</ul>
<h2>Featured Articles</h2>
<ul>
<li><a href="https://dev.to/yourusername/article-title">How I Built This Portfolio</a></li>
<li><a href="https://dev.to/yourusername/api-doc-template">API Documentation Template</a></li>
</ul>
<h2>Publication</h2>
<p>
<a href="https://example.com/publication-link">The Influence of Micro-expressions on Deception Detection</a>
</p>
<h2>Why I Do This</h2>
<p>
I’m driven by a passion for making technology accessible. My goal is to bridge the gap between complex systems and the people who use them — whether they're developers or stakeholders.
</p>
<section id="work-section">
<h2>Let's Work Together</h2>
<p>
I’m available for freelance and contract-based technical writing. Email me at
<a href="mailto:youremail@example.com">youremail@example.com</a> or check out
<a href="https://github.com/yourusername" target="_blank">my GitHub</a>.
</p>
</section>
</main>
<footer>© 2025 Your Name</footer>
</body>
</html>
🎨 Step 3: Add Styling in style.css
copy this to a file called style.css
body {
background-color: #121212;
color: #f5f5f5;
font-family: 'Inter', sans-serif;
margin: 0;
padding: 0;
}
nav {
background: linear-gradient(to right, #6a11cb, #2575fc);
padding: 1rem 2rem;
display: flex;
justify-content: space-between;
align-items: center;
}
📬 Step 4: Add a Contact Page
Create a contact.html file and mirror the design — just include your email address and links.
🌍 Step 5: Add Your Sitemap
Create a file called sitemap.xml:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://yourusername.github.io/</loc>
</url>
<url>
<loc>https://yourusername.github.io/contact.html</loc>
</url>
</urlset>
Upload it to your GitHub repo root.
📈 Step 6: Submit to Google
Go to Google Search Console
Add your site as a URL prefix
Choose HTML tag → Paste into
Go to “Sitemaps” → Add sitemap.xml
Done!!!.
Let me know if you want to build something similar! I’d love to help others make docs look as great as the code they explain.
For Clarity, you can go to my GitHub repo https://github.com/SandraMeshack/sandrameshack.github.io
Top comments (0)