GitHub Pages Portfolio and SEO Guide 2026

Baguette Tools · February 2026 · 12 min read
Web Dev SEO GitHub Pages Portfolio

GitHub Pages is the best free hosting option for developer portfolios in 2026. It is fast, reliable, supports custom domains with free SSL, and deploying is a git push. No server to manage, no hosting bill, no vendor lock-in. Your site is a repository, which means version control, collaboration, and transparency are built in.

But most developer portfolios on GitHub Pages are invisible to search engines. They have no meta tags, no structured data, no sitemap, and page titles like "index.html". This guide covers how to set up a GitHub Pages portfolio that actually ranks, from initial setup to advanced SEO techniques. The baguette.art portfolio is built entirely on GitHub Pages using the techniques described here.

Setting Up GitHub Pages

Repository Setup

You have two options for GitHub Pages hosting. The first is a user site at username.github.io. Create a repository named exactly username.github.io and the main branch automatically deploys to that URL. The second is a project site, where any repository can serve pages from the gh-pages branch or a /docs folder, accessible at username.github.io/repo-name.

For a portfolio, use the user site. It gives you a cleaner URL and is the expected convention. Create the repository, add an index.html, push it, and your site is live within a minute.

mkdir username.github.io
cd username.github.io
git init
echo "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>" > index.html
git add index.html
git commit -m "Initial commit"
git remote add origin git@github.com:username/username.github.io.git
git push -u origin main

Custom Domain Configuration

A custom domain is the single most impactful thing you can do for your portfolio's credibility. A .art, .dev, or .io domain costs $10-15 per year and immediately makes your site look professional.

The setup has two steps. First, add a CNAME file to your repository root containing your domain (e.g., baguette.art). Second, configure DNS at your registrar. For an apex domain, add these A records pointing to GitHub's IP addresses:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

For a www subdomain, add a CNAME record pointing to username.github.io. Once DNS propagates (up to 48 hours, usually under an hour), go to your repository settings under Pages and check "Enforce HTTPS". GitHub provisions a free SSL certificate through Let's Encrypt automatically.

Jekyll vs Static HTML

GitHub Pages has native Jekyll support. Push Markdown files and Jekyll templates to your repository and GitHub builds the HTML automatically. This is convenient for blogs but adds complexity and constraints for portfolios.

When to Use Jekyll

When to Use Static HTML

For most developer portfolios, static HTML is the better choice. You get faster page loads (no Jekyll build overhead), zero dependency on GitHub's build system, and complete control. If you later need templating, you can use a simple build script or a lightweight static site generator like Eleventy locally and push the output.

SEO Fundamentals for GitHub Pages

Title Tags

The title tag is the most important on-page SEO element. Every page needs a unique, descriptive title under 60 characters. The format should be: Primary Keyword - Secondary Context | Brand. Do not use generic titles like "Home" or "Portfolio".

<!-- Bad -->
<title>My Portfolio</title>

<!-- Good -->
<title>Jane Smith - Full Stack Developer | React, Node.js, AWS</title>

<!-- Good for a project page -->
<title>WeatherDash - Real-Time Weather Dashboard Built with React</title>

Meta Descriptions

The meta description appears in search results below your title. Keep it under 160 characters, make it actionable, and include your primary keyword naturally. Every page needs a unique description. If you skip it, Google will pull random text from your page, which usually looks terrible in search results.

<meta name="description" content="Full stack developer specializing
in React and Node.js. View projects, open source work, and technical
writing.">

Canonical URLs

Add a canonical URL to every page. This tells search engines the authoritative URL for the content, preventing duplicate content issues if your site is accessible at both www and non-www versions, or at both .github.io and your custom domain.

<link rel="canonical" href="https://yourdomain.com/page-name.html">

Structured Data (JSON-LD)

Structured data helps search engines understand what your page is about and can produce rich results (enhanced search listings). For a portfolio, the most useful schema types are Person for your homepage, Article for blog posts, and SoftwareApplication for projects.

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "Person",
    "name": "Jane Smith",
    "url": "https://janesmith.dev",
    "jobTitle": "Full Stack Developer",
    "sameAs": [
        "https://github.com/janesmith",
        "https://linkedin.com/in/janesmith",
        "https://twitter.com/janesmith"
    ],
    "knowsAbout": ["React", "Node.js", "AWS", "TypeScript"]
}
</script>

For project pages, use the SoftwareApplication type:

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "SoftwareApplication",
    "name": "WeatherDash",
    "url": "https://janesmith.dev/weatherdash",
    "applicationCategory": "UtilitiesApplication",
    "operatingSystem": "Web Browser",
    "author": {
        "@type": "Person",
        "name": "Jane Smith"
    },
    "description": "Real-time weather dashboard with 7-day forecasts"
}
</script>

Sitemap and robots.txt

Create a sitemap.xml in your repository root listing every page on your site. This helps search engines discover all your content, especially pages that are not linked from your homepage.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://yourdomain.com/</loc>
        <lastmod>2026-02-26</lastmod>
        <priority>1.0</priority>
    </url>
    <url>
        <loc>https://yourdomain.com/projects.html</loc>
        <lastmod>2026-02-26</lastmod>
        <priority>0.8</priority>
    </url>
</urlset>

Add a robots.txt file pointing to your sitemap:

User-agent: *
Allow: /
Sitemap: https://yourdomain.com/sitemap.xml

Submit your sitemap to Google Search Console after setting it up. This accelerates indexing significantly compared to waiting for Google to discover your site organically.

Performance Optimization

GitHub Pages serves content through a global CDN (Fastly), which means your static files are already delivered fast. But page weight and rendering performance are your responsibility.

Minimize Page Weight

The median web page in 2026 is over 2.5 MB. A well-built portfolio page should be under 200 KB total, including all CSS, JavaScript, and images. System fonts alone save 100-300 KB over custom web fonts. Inline your CSS for pages under 20 KB of styles. Use loading="lazy" on images below the fold.

<!-- Lazy load images -->
<img src="project-screenshot.webp" alt="WeatherDash screenshot"
     loading="lazy" width="720" height="405">

<!-- Specify dimensions to prevent layout shift -->

Image Optimization

Use WebP format for all images. It provides 25-35% smaller files than JPEG at equivalent quality. Always specify width and height attributes to prevent Cumulative Layout Shift (CLS), which hurts your Core Web Vitals score.

For screenshots and diagrams, consider whether an SVG or even a CSS-only illustration would work instead. Vector graphics scale perfectly and are often smaller than raster images for simple shapes.

Core Web Vitals

Google uses three Core Web Vitals metrics as ranking signals: Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS). A static HTML portfolio on GitHub Pages should pass all three easily if you follow these rules:

Content Strategy for Developer Portfolios

Project Pages

Each significant project deserves its own page. Do not just list project names with GitHub links. Write a paragraph explaining what the project does, why you built it, what technical decisions you made, and what you learned. Include a screenshot or demo link. This gives search engines content to index and gives visitors context that a README does not provide.

Technical Articles

Publishing technical articles on your portfolio is the most effective long-term SEO strategy for developers. Each article targets specific search queries and brings organic traffic to your site. Over time, a portfolio with 10-20 well-written articles will receive significantly more traffic than one with only project listings.

Target long-tail keywords that match what developers actually search for. "How to set up WebGL shaders" will rank faster than "WebGL tutorial" because it is more specific and has less competition. For a deeper comparison of hosting browser-based tools versus desktop applications, see our article on browser tools vs desktop apps.

Internal Linking

Link between your pages naturally. Your project pages should link to relevant articles. Your articles should link to related projects. Your homepage should link to everything. Internal links help search engines understand your site structure and distribute ranking authority across pages.

Free Hosting Advantages

The cost advantage of GitHub Pages extends beyond the zero price tag. You eliminate an entire category of operational concerns:

The limitations are real but narrow. GitHub Pages does not support server-side processing, so you cannot run a database or API. The repository size limit is 1 GB, and there is a soft bandwidth limit of 100 GB per month. For a portfolio with articles, projects, and web tools, you will never hit these limits.

Advanced Techniques

GitHub Actions for Automation

Use GitHub Actions to automate sitemap generation, link checking, HTML validation, and image optimization on every push. A simple workflow can run html-validate and broken-link-checker as a pre-merge check, catching SEO issues before they go live.

# .github/workflows/seo-check.yml
name: SEO Check
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate HTML
        run: npx html-validate "**/*.html"
      - name: Check links
        run: npx broken-link-checker https://yourdomain.com --recursive

Open Graph and Social Previews

When someone shares your portfolio link on Twitter, LinkedIn, or Slack, Open Graph tags control what preview appears. Add og:title, og:description, og:image, and og:url tags to every page. Create a dedicated social preview image (1200x630 pixels) for your homepage.

Analytics Without Cookies

Use a privacy-respecting analytics tool like Plausible, Fathom, or Umami instead of Google Analytics. These tools do not use cookies, so you do not need a cookie consent banner, which improves both user experience and page load speed. Plausible's script is under 1 KB.

Checklist: Launch Your Portfolio

Before you consider your portfolio done, verify each of these:

  1. Every page has a unique <title> under 60 characters
  2. Every page has a unique meta description under 160 characters
  3. Every page has a canonical URL
  4. Homepage has Person structured data
  5. Project pages have SoftwareApplication structured data
  6. Articles have Article structured data
  7. sitemap.xml lists every page
  8. robots.txt references the sitemap
  9. Custom domain configured with HTTPS enforced
  10. All images are WebP with width/height attributes
  11. No render-blocking JavaScript
  12. Passes Google PageSpeed Insights with 90+ on mobile
  13. Open Graph tags on every page
  14. Submitted to Google Search Console

A developer portfolio is never finished, but if you check every item on this list, you have a solid foundation that will rank, load fast, and represent your work professionally. The rest is content: keep building projects, keep writing about what you learn, and your portfolio will grow its search presence over time.

Related Articles