GitHub Metadata

GitHub Metadata is a Jekyll plugin that propagates the site.github namespace and sets default values so GitHub Pages builds work out of the box.

What is GitHub Metadata?

GitHub Metadata is a Ruby gem and Jekyll plugin that injects repository information into your Jekyll site under the site.github namespace. It runs on any Jekyll build or serve command, reads metadata from the GitHub repository using the Octokit library, and sets fallback values for site.title, site.description, site.url, and site.baseurl when they are not already defined. The project is maintained by the Jekyll team and is the mechanism that powers GitHub Pages' automatic site.github data.

Key Features

• site.github namespace — Exposes repository metadata such as owner, name, tagline, and other GitHub fields as a structured object usable in templates.
• Automatic site defaults — Sets site.title to the repository name, site.description to the repository tagline, site.url to the GitHub Pages domain (cname or user domain), and site.baseurl to the project name for project pages when none are set.
• Simple installation — Add gem "jekyll-github-metadata" to your Gemfile and list jekyll-github-metadata under plugins in _config.yml, then run bundle install.
• Jekyll integration — Runs automatically on every build or serve once installed, with no extra configuration required for basic use.
• Authentication support — Documented authentication options for sites that need to access private or extended repository data.
• Configuration options — A dedicated configuration page details how to control the plugin's behavior.
• Edit on GitHub link — Includes documentation for generating "Edit on GitHub" links, useful for documentation sites.
• Built on Octokit — Uses the official Ruby Octokit library to fetch metadata from the GitHub API.

Who is it for?

• Jekyll theme developers — They can rely on site.github to display repository info without writing their own GitHub API calls.
• Documentation site maintainers — They can use the plugin to set baseurl and url correctly for project pages, plus add "Edit on GitHub" links.
• GitHub Pages users — Any Jekyll user publishing to GitHub Pages benefits from automatic default values that make local builds match the production Pages environment.

What can you do with GitHub Metadata?

• Display repository metadata: Access fields like owner, name, and tagline in Liquid templates through site.github without manual configuration.
• Set correct URLs automatically: Let the plugin assign site.url (the Pages domain) and site.baseurl (the project name) so asset links and canonical URLs work on project pages.
• Add "Edit on GitHub" links: Follow the documented pattern to include quick edit links on documentation pages.

How does GitHub Metadata work?

Install the gem and add it as a Jekyll plugin. During each build or serve, the plugin queries the GitHub API via Octokit and injects the resulting metadata into the site.github variable, then fills in any missing site configuration values. Authentication can be added for higher API limits or private repositories.

FAQ

Is GitHub Metadata free?

Yes, the plugin is open source under the Jekyll project and available as a Ruby gem.

Does GitHub Metadata work with Jekyll versions before 3.5.0?

For Jekyll versions earlier than 3.5.0, use the gems key in _config.yml instead of plugins.

What metadata is exposed?

The plugin exposes the full GitHub repository metadata object as site.github, including fields like the repository name, description, URLs, and other API properties.