# How to Configure Jekyll Plugins and Custom Metadata for GitHub Pages

> Learn to configure Jekyll plugins and custom metadata for GitHub Pages. Customize your site using _config.yml and YAML front-matter for richer content.

- Repository: [Tim Green/github-cheat-sheet](https://github.com/tiimgreen/github-cheat-sheet)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To configure Jekyll plugins and custom metadata for GitHub Pages, enable whitelisted plugins in your [`_config.yml`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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.

```yaml

# _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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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:

```liquid
<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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/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:

```markdown
---
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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_config.yml), accessing repository metadata, and utilizing custom front-matter variables.

**[`_config.yml`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_config.yml):**

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

```

**[`index.md`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/index.md):**

```markdown
---
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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_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`](https://github.com/tiimgreen/github-cheat-sheet/blob/main/_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.