Understanding layout assignment

The layout a page uses is controlled by its layout Frontmatter property. The layout value is a string that must match the name of a file in the _layouts folder.

For example: If layout: general, the page will use the _layouts/general.html layout file.

A page’s layout property can be assigned at either the collection or page level.

Collection-level assignment

All Frontmatter properties - not just layout - can be defined at the collection level. This means that instead of defining a property in a single page, it’s defined in _config.yml.

In _config.yml, the defaults property contains default settings for collections in the Stitch Docs. For example:

defaults:    
  - scope:
      type: developer-content         ## name of the collection
    values:
      layout: developer               ## default layout
      display-summary: "false"        ## controls if page.summary displays in the output
      toc: false                      ## controls the display of the table of contents

This means that for the _developer-content collection, pages in this collection will default to using the developer layout.

Unless different values are defined at the page level, all pages in this collection will, by default, use the values defined in _config.yml.

Page-level assignment

If assigned at the page level, the layout property will be present in the page’s Frontmatter. In this example, the page has a value of layout: tutorial:

## _developer-content/connect/guides/api/configure-oauth-for-a-source.md

title: Configure OAuth for a Data Source with the Connect API
permalink: /developers/stitch-connect/guides/configure-oauth-for-a-source-with-stitch-connect

layout: tutorial

Note: Any property set at the page level overrides properties set at the collection level.

Understanding layout inheritance

Layouts in Jekyll can inherit other layouts. This allows you to add some formatting for a portion of documents while allowing other documents to only use the base layout.

To do this, specify the inherited layout in the layout’s Frontmatter. For example: This is the general.html layout (_layouts/general.html):

---
layout: page
---

For the general layout, it means that it inherits everything contained in the page layout, including any layouts that page may also inherit.

The chart below shows the hierarchy of inheritance for all layouts in the Stitch Docs, with default as the parent:

Layout reference

In this section is a list of the layouts contained in the Stitch Docs:

Name: The name of the layout
Purpose: A description of the layout
Notes: Additional info about the layout
Layout: The layout that this layout inherits
Sidebar: The sidebar(s) that can be used with the layout
Collection dependencies(s): The collections that use this layout as a default (defined in _config.yml)
File dependencies(s): The files used in the layout
Example: A link to a Stitch Docs page that uses the layout

Note: You may need to fully expand the record to view all its info.

Resources

Last updated: 21 July 2021