How to Configure Jekyll Plugins and Custom Metadata for GitHub Pages

To configure Jekyll plugins and custom metadata for GitHub Pages, enable whitelisted plugins in your _config.yml file, access repository metadata through the site.github namespace, and define page-specific variables using YAML front-matter in your Markdown files.

GitHub Pages automatically builds Jekyll sites from your repository, but unlocking advanced features requires specific configuration steps documented in the tiimgreen/github-cheat-sheet repository. By leveraging the platform's built-in repository metadata object, approved plugin whitelist, and standard YAML front-matter, you can create dynamic, data-driven static sites without maintaining a separate build pipeline.

Enabling Whitelisted Plugins in _config.yml

GitHub Pages runs Jekyll in a safe mode that restricts plugin execution to a small whitelist. According to the tiimgreen/github-cheat-sheet documentation at README.md lines 90–95, you must declare supported plugins in your configuration file using the plugins array (or the legacy gems key).

Two commonly utilized whitelisted plugins are Jemoji, which renders :emoji: syntax as Unicode characters, and jekyll-mentions, which automatically converts @username references into hyperlinks to GitHub profiles.

# _config.yml

title: My GitHub Pages Site
remote_theme: pages-themes/cayman@v0.2.0
plugins:
  - jemoji
  - jekyll-mentions

Attempting to use plugins outside the official whitelist will cause GitHub Pages to ignore them during the build process, as the platform does not execute arbitrary Ruby code for security reasons.

Accessing Repository Metadata via site.github

GitHub Pages injects a global site.github object into every Jekyll build, exposing repository data without requiring API calls. As documented in README.md lines 90–95, this namespace contains fields such as project_title, owner_name, repository_url, repository_name, and issues_url.

You can reference these variables in any Liquid template using standard dot notation:

<p>Project: {{ site.github.project_title }}</p>
<p>Owner: {{ site.github.owner_name }}</p>
<p>Repository: <a href="{{ site.github.repository_url }}">{{ site.github.repository_name }}</a></p>
<p>Issues: <a href="{{ site.github.issues_url }}">View Open Issues</a></p>

This automatic injection eliminates the need to hardcode repository-specific URLs or manually update configuration values when forking a project.

Defining Custom Metadata with YAML Front-Matter

Individual pages and posts can declare custom variables through YAML front-matter, a block delimited by triple dashes at the top of any Markdown file. The github-cheat-sheet repository notes at README.md lines 97–99 that GitHub renders this block as a horizontal table, while Jekyll parses the key-value pairs into the page namespace.

Standard metadata keys include title, layout, description, and tags, though you may define arbitrary custom fields:

---
title: "Welcome to My Project"
layout: default
description: "A technical documentation site powered by Jekyll"
custom_variable: "Hello World"
---

# {{ page.title }}

{{ page.description }}

Custom value: {{ page.custom_variable }}

These variables are accessible throughout the page's template via page.<key> syntax, enabling conditional layouts and dynamic content generation.

Complete Implementation Example

The following example combines all three configuration methods: enabling plugins in _config.yml, accessing repository metadata, and utilizing custom front-matter variables.

_config.yml:

title: Developer Documentation
plugins:
  - jemoji
  - jekyll-mentions

index.md:

---
title: "Home"
layout: default
author: "Documentation Team"
---

# {{ page.title }}

Welcome to **{{ site.github.project_title }}** maintained by **{{ site.github.owner_name }}**! 

This site supports emoji rendering :rocket: and user mentions.

Current repository: [{{ site.github.repository_name }}]({{ site.github.repository_url }})

Author: {{ page.author }}

Summary

• Whitelist restrictions: GitHub Pages only executes plugins listed in the official whitelist, configured via the plugins array in _config.yml.
• Repository data: The site.github namespace automatically exposes repository metadata including URLs, owner information, and project titles without manual configuration.
• Page variables: YAML front-matter at the top of Markdown files defines page-specific metadata accessible through the page object in Liquid templates.
• Security model: The platform builds sites in safe mode, ignoring custom Ruby plugins while providing sanitized alternatives like Jemoji and jekyll-mentions.

Frequently Asked Questions

Which Jekyll plugins are supported on GitHub Pages?

GitHub Pages maintains a strict whitelist of plugins that includes jemoji for emoji rendering, jekyll-mentions for auto-linking GitHub usernames, and jekyll-sitemap for SEO optimization. You can enable these by adding them to the plugins list in your _config.yml file. Custom plugins or gems outside this list will be silently ignored during the build process.

How do I access repository information in my Jekyll templates?

GitHub Pages automatically populates the site.github object with repository metadata such as repository_url, owner_name, project_title, and issues_url. Reference these variables using Liquid syntax like {{ site.github.repository_url }} anywhere in your layouts, includes, or page content.

What is the difference between site.github and page variables?

The site.github namespace contains repository-level metadata injected automatically by GitHub Pages, while page variables contain document-specific metadata defined manually in YAML front-matter at the top of individual Markdown files. Use site.github for repository links and ownership data, and page for article-specific attributes like titles, authors, or categories.

Why isn't my custom plugin working on GitHub Pages?

GitHub Pages executes Jekyll in safe mode, which prevents the execution of arbitrary Ruby plugins for security reasons. If your plugin is not on the official whitelist, the build process will ignore it. To use custom plugins, you must either switch to building your site locally or using GitHub Actions to deploy pre-built static files rather than relying on the automatic GitHub Pages build process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}