Primer

Primer is a Jekyll theme for GitHub Pages that turns a standard Jekyll site into a clean, GitHub-styled website with configurable title, description, download links, and Google Analytics.

What is Primer?

Primer is an official GitHub Pages theme maintained in the pages-themes organization on GitHub. It is a Jekyll theme that takes your site's configuration and content, then renders a static website with a default layout that follows the Primer design system. You can use it by adding a single remote_theme line to your _config.yml, or by installing the jekyll-theme-primer gem locally. The theme's repository includes a preview site and a documented set of customization options.

Key Features

• Remote theme installation — Use remote_theme: pages-themes/[email protected] in _config.yml so GitHub Pages fetches the theme automatically at build time.
• Configuration variables — Set title and description to populate the site header; optionally enable show_downloads and supply a google_analytics tracking ID.
• Custom stylesheet support — Create assets/css/style.scss and import the theme with @import "{{ site.theme }}";, then override Sass variables before the import.
• Layout and include overrides — Add custom files to _includes for changes like a favicon, or copy the default _layouts/default.html from the theme's repository and edit it extensively.
• Google Analytics customization — Replace the theme's built-in analytics code entirely by pasting the latest snippet into _includes/head-custom-google-analytics.html.
• GitHub URL overrides — Override auto-generated links such as site.github.zip_url by defining equivalent keys under github: in _config.yml.

Who is it for?

• GitHub Pages beginners — Anyone who wants a functional Jekyll site without learning theme development; adding the remote_theme line is enough to publish.
• Open-source project maintainers — Teams that need a documentation or project landing page with GitHub-style default styling and optional download links.
• Developers customizing Jekyll themes — Users who want a simple baseline layout that can be copied into _layouts and modified, with documented Sass variable overrides.

What can you do with Primer?

• Launch a project site quickly — Configure the theme in minutes and rely on GitHub Pages for automatic building and hosting.
• Style with Sass overrides — Change colors, fonts, and layout rules by editing assets/css/style.scss with new variable values.
• Add analytics tracking — Set your Google Analytics ID in the config, or drop in the newest code via the head include.
• Enable download buttons — Turn on show_downloads to make the theme link to archive files from your repository.

How does Primer work?

Primer works through Jekyll's theme mechanism. When you set remote_theme in your site's _config.yml, GitHub Pages pulls the theme from the pages-themes repository during each build. The theme's default layout then renders your site's title, description, and content, and it reads configuration variables from _config.yml to toggle optional features like download links and analytics.

FAQ

How do I install Primer?

Add remote_theme: pages-themes/[email protected] to your _config.yml. If you don't already have the jekyll-remote-theme plugin in your plugins list, add it. For local development, add the github-pages gem to your Gemfile and run bundle exec jekyll serve.

Can I customize the colors and fonts?

Yes. Create a file at assets/css/style.scss and put the @import line for the theme at the top, then define your desired Sass variable values before that import. Any custom CSS you add after the import will also be included.

How do I change the layout?

For small changes like a custom favicon, add files to your local _includes folder. For larger changes, copy the theme's _layouts/default.html into your repository as /_layouts/default.html and edit the copied template to suit your needs.

Does Primer support Google Analytics?

Yes, set the google_analytics variable in _config.yml with your tracking ID. The theme includes a head include specifically for this; you can also overwrite that file with the latest Analytics code if you need a newer version.

How can I override GitHub-generated URLs?

Look at the theme's default layout to find the variable you want to override, such as site.github.zip_url. Then, in _config.yml, create a github: section and list the same property name (without site.) with the URL you want to use.