Layouts

The theme ships four layouts. All are available to any page in your site via the layout front matter key.

default

The main two-column layout. Use this for all regular content pages.

---
layout: default
title: My Page
---

Renders:

  • Fixed left sidebar with the site title, search box, and auto-generated navigation
  • Main content area on the right with Primer markdown-body styles applied
  • Mobile header with hamburger toggle at narrow viewports

This is the layout you will use for almost every page.

home

A thin wrapper around default. Identical output — it simply renders `<h1 id="installation">Installation</h1>

Option A — Use the template (recommended)

The fastest way to get started:

  1. Go to primer2-template and click Use this template → Create a new repository
  2. In your new repo, go to Settings → Pages and set Source to GitHub Actions
  3. Edit _config.yml with your site title and description
  4. Push a change — your site deploys automatically

Option B — Add to an existing site

Add to your site’s _config.yml:

remote_theme: bagustris/primer2-theme
plugins:
  - jekyll-remote-theme
  - jekyll-seo-tag

Add to your Gemfile:

gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme"

Then run:

bundle install
bundle exec jekyll serve

Requirements

  • Jekyll 3.5–4.x
  • Ruby 2.4+
  • Works with GitHub Pages out of the box (no custom build step needed)

` inside the default layout. Provided for semantic clarity when you want your root index.md to declare itself as the home page.

---
layout: home
---

Tip: Using layout: default on index.md works just as well. home is purely a naming convention.

page

Another thin wrapper around default. Semantically distinguishes a generic static page (About, Contact, etc.) from a post or the home page.

---
layout: page
title: About
---

Output is identical to default.

post

Wraps default. Intended for dated blog posts. No extra rendering logic is added by the theme beyond the default layout, but using layout: post follows Jekyll convention and makes it straightforward to add post-specific styling later.

---
layout: post
title: "My First Post"
date: 2025-01-01
---

Note: The sidebar navigation includes all pages that have a layout set (unless nav_exclude: true is present). Blog posts with layout: post will therefore appear in the sidebar by default. Add nav_exclude: true to any post you want to keep out of the nav.

Overriding a layout

Copy the layout file from the theme into your site’s _layouts/ directory and edit it freely. Jekyll will prefer your local copy over the theme’s.

# Example: override the default layout
cp $(bundle show jekyll-theme-primer)/_layouts/default.html _layouts/default.html

For smaller additions (favicon, custom fonts, analytics) prefer the _includes/head-custom.html hook instead of overriding the full layout. See Customization for details.

This site is open source. Improve this page.