How to Make a Reusable HTML Head for GitHub Pages

When hosting a static site on GitHub Pages, repeating the same HTML head section across multiple files becomes tedious and error-prone. You want a DRY (Don’t Repeat Yourself) approach to manage the <head> content efficiently without sacrificing performance. Let’s explore how to achieve this using GitHub Pages-supported technologies, while enhancing functionality for real-world use cases.

Redundant Code in HTML Head

Your current HTML structure includes boilerplate code for the <head> section, which is duplicated across every page:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Home</title>
    <link rel="icon" type="image/png" href="assets/favicon.png">
    <link rel="stylesheet" href="style.css">
    <link rel="stylesheet" href="shadowStyle.css">
</head>
<body>
</body>
</html>

Run HTML

Manually updating this for each page is time-consuming. Let’s automate it!

Jekyll Includes (Recommended)

GitHub Pages natively supports Jekyll, a static site generator. Use Jekyll’s templating to reuse the <head> section.

Configure Jekyll

Create a _config.yml file to enable Jekyll processing:

title: My Site
theme: minima
include: [_includes]

Organize your files:

.
├── _includes/
│   └── head.html
├── _config.yml
├── index.html
└── about.html

Create the Reusable Head

Inside _includes/head.html, define the <head> section with variables:

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ page.title }}</title>
    <link rel="icon" type="image/png" href="{{ page.favicon }}">
    {% for css in page.styles %}
    <link rel="stylesheet" href="{{ css }}">
    {% endfor %}
</head>

Use the Include in Pages

Add Jekyll front matter to your HTML files (e.g., about.html):

---
title: About Me
favicon: assets/favicon.png
styles:
  - style.css
  - shadowStyle.css
---
<!DOCTYPE html>
<html lang="en">
{% include head.html %}
<body>
    <!-- Page content -->
</body>
</html>

How It Works:
Jekyll compiles your pages at build time, injecting the <head> content statically. No runtime computation—just pre-rendered HTML!

JavaScript Dynamic Injection (Fallback)

If Jekyll isn’t an option, use JavaScript to inject the <head> dynamically. Add this script to your HTML files:

<!DOCTYPE html>
<html lang="en">
<head>
    <script>
        // Define reusable head configuration
        const setupHead = ({ title, favicon, styles }) => {
            document.title = title;
            
            const faviconLink = document.createElement('link');
            faviconLink.rel = 'icon';
            faviconLink.href = favicon;
            document.head.appendChild(faviconLink);

            styles.forEach(href => {
                const link = document.createElement('link');
                link.rel = 'stylesheet';
                link.href = href;
                document.head.appendChild(link);
            });
        };

        // Configure for this page
        setupHead({
            title: 'Home',
            favicon: 'assets/favicon.png',
            styles: ['style.css', 'shadowStyle.css']
        });
    </script>
</head>
<body>
</body>
</html>

Pros:

No build tool required.
Easy to customize per page.

Cons:

Slight runtime overhead (negligible for small sites).
FOUC (Flash of Unstyled Content) if scripts load slowly.

Enhancing Functionality

Let’s add practical features to the Jekyll approach:

Default Values

Modify _includes/head.html to use defaults if variables are missing:

<title>{{ page.title | default: site.title }}</title>
<link rel="icon" type="image/png" href="{{ page.favicon | default: '/assets/default-favicon.png' }}">

Conditional Stylesheets

Load CSS files only on specific pages:

{% if page.use_shadow_style %}
    <link rel="stylesheet" href="shadowStyle.css">
{% endif %}

SEO Optimization

Add meta descriptions and Open Graph tags dynamically:

<meta name="description" content="{{ page.description | default: site.description }}">
{% if page.image %}
<meta property="og:image" content="{{ page.image }}">
{% endif %}

Final Thought

For GitHub Pages, Jekyll includes are the gold standard. They eliminate redundancy at build time, ensure performance, and integrate seamlessly with GitHub’s infrastructure. Reserve JavaScript for edge cases where Jekyll isn’t feasible.

By adopting these methods, you’ll reduce coding effort and create a maintainable, scalable site structure. Now go build something awesome without rewriting the same <head> a hundred times!