Thomas Gumbricht

Scientist working part time for Karttur and part time for Stockholm University.

Pages - a quick tutorial

  1. Create the pages document in the folder _pages, name it logically,
  2. set pages primary keys either:
    • in _config.yml, or
    • as front matter in the pages document itself,
  3. set the path to the new pages document front matter as the parameter permalink,
  4. set the parameter title in the front matter,
  5. add other options in the front matter, including overriding the _config.yml defaults.

For more details read on or visit the Jekyll document on Pages.

This article itself is an example of a page, created using the theme Minimal Mistakes.

Pages

As pages are unitary documents, unassociated with other documents in the same site, they are typically published in separate sub-folders (= sub-directories). Sub-folders that contain only a single index.html file. The path to the sub-folder from the site root is typically given in the front matter by the key (parameter) permalink. This also means that a pages markdown document can be put anywhere, it is the parameter permalink that defines where the resulting html file ends up in the published web-site. One example is to put the about.markdown document in the root folder, but set its permalink to either pages or about.

_config.yml and front matter

To be linked properly the front matter of a page only needs to contain keys for permalink and a title:

permalink: /jekyllpages/
title: "Pages in Jekyll"

For the theme Minimal Mistakes this is the recommended setting for pages in _config.yml:

defaults:
  # _pages
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true

Transferred to the front matter of the pages document itself this becomes:

layout: single
author_profile: true

Combined with the permalink and title keys, the complete front matter then becomes:

layout: single
author_profile: true
permalink: /jekyllpages/
title: "Pages in Jekyll"

Key values set in the pages file front matter has precedence over values set in _config.yml if a key:value pair is set in both.

Table of content

Editing _config.yml you can add additional elements, like a table of content (toc) as in this example page:

defaults:
  # _pages
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true
      toc: true

Minimal Mistakes even allows you to set the title and logo for the toc.

You can also add the key toc for individual pages documents:

layout: single
author_profile: true
permalink: /jekyllpages/
title: "Pages in Jekyll"
toc:true

Again, if the toc key is set in both the _config.yml and the document own front matter, the latter will take precedence.

Linking to your pages

In this example the index.html generated from the pages.md file will end up in the site under the path:

./jekyllpages/index.html

This url is not linked to your site root (front/home) page. The options for directing site visitors to your single page include:

  1. as a main menu item,
  2. adding a customised sidebar navigation, or
  3. as an explicit url link in the root page (or any page on your site).

The main menu is defined in the file ./_data/navigation.yml.

If your site does not contain the file ./_data/navigation.yml it is instead found in the “gem” that your jekyll theme is based on. To find the “gem”, open the terminal that contains your site and execute the command:

$ bundle info minimal-mistakes.

The terminal should then report something like:

* minimal-mistakes-jekyll (4.26.2)
Summary: A flexible two-column Jekyll theme.
Homepage: https://github.com/mmistakes/minimal-mistakes
Path: /Users/thomasgumbricht/.gem/ruby/3.3.5/gems/minimal-mistakes-jekyll-4.26.2

under the reported path look for

./_data/navigation.yml

Copy this file to your site and the local copy will take precedence over the “gem” file. You can now edit the local copy of navigation.yml to have the following main menu:

# main links
main:
  - title: "About"
    url: /about/
  - title: "Front"
    url: /
  - title: "Pages"
    url: /jekyllpages/

To add tooltips that appear when the mouse is hoovered over the menu item, edit navigation.yml and add description keys:

# main links
main:
  - title: "About"
    url: /about/
    description: about Karttur
  - title: "Front"
    url: /
    description: Site root
  - title: "Pages"
    url: /jekyllpages/
    description: jekyll pages as part of your site

Custom sidebar navigation

Minimal Mistakes allows you to add a customised sidebar navigation. This requires three steps:

  1. name the custom navigation and list the links,
  2. edit navigation.yml with the name and the links, and
  3. add the name in either the front matter of individual files or in _config.yml.

Here is an example of a customised navigation, named jekylldocs, linking to three different urls:

jekylldocs:
  - title: Jekyll doc system
    children:
      - title: "Pages"
        url: /jekyllpages/
      - title: "Posts"
        url: /jekyllposts/
      - title: "Collections"
        url: /jekyllcollections/

The above code should be written to the local site copy of navigation.yml.

Then add the following lines to the front matter of the files where you want the sidebar navigation to appear:

sidebar:
  nav: "jekylldocs"

The complete front matter then becomes something like:

layout: single
author_profile: true
permalink: /jekyllpages/
title: "Pages in Jekyll"
excerpt: "How to set front matter in Jekyll pages and options for pages layout and content using the theme Minimal Mistakes."

sidebar:
  nav: "jekylldocs"

I add my customisations at the end of the front matter (or _config.yml), including a comment. In that way I can find them easily if I want to remove, change or transfer my customisations to new versions of Jekyll or Minimal Mistakes.

Alternatively edit _config.yml defaults:

...
defaults:
  # _pages
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true
      toc: true
      sidebar:
        nav: "jekylldocs"
...

The last option for linking to a single pages document is to use an explicitly written html tag linking to Pages in Jekyll:

[Pages in Jekyll](jekyllpages)

Or, using the latest Jekyll syntax that assembles all explicit urls in markdown (.md) files:

[Pages in Jekyll][jekyllpages]
...
...
[jekyllpages]: url/to/jekyllpages

Resources

Jekyll - pages

Minimal Mistakes

Minimal Mistakes - configuration

Minimal Mistakes - table of contents

Minimal Mistakes - sidebar navigation

Minimal Mistakes - nested and mixed lists