The sidenav in the Stitch Docs is based on this theme.

In this guide, you’ll learn:

• How sidenavs are assigned and formatted
• About the types of sidenavs in the Stitch Docs
• How to update a sidenav
• About the sidebar includes in the Stitch Docs and how each one is used

Understanding how sidenavs are assigned and formatted

• Sidenav assignment
• Sidenav formatting and includes

Sidenav assignment

The sidenav a page uses depends on two Frontmatter properties:

• layout: The name of the layout the page is using
• sidebar: The name of the sidenav the page is using

Like all other page attributes, these values are assigned to a page through Frontmatter.

A page’s layout and sidebar properties can be assigned at either the collection or page level.

Sidenav formatting and includes

When a page is built, Jekyll reads the page’s layout and sidebar values to determine the correct sidenav include to use.

These values are passed to the _includes/layout/sidebar.html include, which first looks at the page.layout value:

{% case page.layout %}
    {% when 'changelog' %}
        {% include layout/sidebars/changelog-sidebar.html %}
    {% when 'developer' %}
        {% include layout/sidebars/developer-sidebar.html %}
    {% when 'tutorial' %}
        {% if page.use-tutorial-sidebar == false %}
            {% include layout/sidebars/general-sidebar.html %}
        {% else %}
            {% include layout/sidebars/tutorial-sidebar.html %}
        {% endif %}
    {% else %}
      {% if page.sidebar == 'on-page' %}
        {% include layout/sidebars/on-page-sidebar.html %}
      {% else %}
          {% include layout/sidebars/general-sidebar.html %}
      {% endif %}
{% endcase %}

After selecting the correct include for the page’s layout, Jekyll will run the code contained in the include.

Understanding sidenav types

There are two types of sidenavs in the Stitch Docs:

• Dynamic sidenavs
• Hard-coded sidenavs

Refer to the Sidenav includes section for more info about each of the sidenav includes.

Dynamic sidenavs

Dynamically-generated sidenavs have items that are created based on data in the page’s Frontmatter. Sidenav items on these pages are dependent on the page’s Frontmatter and are unique to that page.

For example: In on-page-sidebar.html, some sidenav items are created based on page.sections.

Hard-coded sidenavs

Hard-coded sidenavs have items that are created based on a data file. Sidenav items on these pages are dependent on the data file backing the sidenav and can be the same across multiple pages.

For example: In general-sidebar.html, items in the sidenav are created based on a data file:

{% assign navigation = site.data.sidebars.stitchnav.all-docs %}

Sidenav data files will (generally) be a list of items made up of categories, sections, and subsections:

## _data/sidebars/stitchnav.yml

all-docs:
- title: sidebar
  categories:

  - title: Account management
    sections:
    - title: Manage your account
      subsections:
        - title: "Change your email and password"
          url: "{{ link.account.email-password }}"

        - title: "Manage your email notifications"
          url: "{{ link.account.manage-notification-settings }}"

        - title: "Update company details"
          url: "{{ link.account.account-settings }}#update-company-information"

Sidenav items will always have a title, and depending on how the sidenav is structured, a url or a handful of other properties.

• Category items can either:

  • Be a single top-level item, in which case they’ll have drop-down: false and url properties:

     - title: "Changelog"
       drop-down: false
       url: "{{ link.changelog.main }}"
    

  • Contain a list of section items with title and either url or sections properties

• Section items can either:
  • Be a single item, in which case they’ll have title and url properties
  • Contain a list of subsection items with title and url properties

• Subsection items will always have title and url properties:

   - title: "Change your email and password"
     url: "{{ link.account.email-password }}"
  

Note: The link method shown in these examples can be used as long as the Linking to internal Stitch docs guide is followed.

Updating sidenavs

The steps for updating a sidenav vary depending on the type of sidenav:

• Hard-coded sidenavs
• Dynamic sidenavs

Hard-coded sidenavs

To update a hard-coded sidenav:

1. Determine which data file the sidenav is using by looking at the sidenav include. Note: All sidenav data files are in _data/sidebars.
2. Open the data file and make your changes.
3. Preview the changes before committing.

Dynamic sidenavs

To update a dynamic sidenav, you just need to modify the data in the page’s Frontmatter (usually page.sections) and save the page’s file.

Sidenav includes

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

• Sidenav: The name of the sidenav include
• Description: A description of the sidenav including how it’s created
• Include: The include that contains the sidenav’s formatting
• Generation: How the sidenav is generated:
  • Dynamic: The sidenav is dynamically generated based on page Frontmatter data
  • Hard-coded: The sidenav is hard-coded and backed by a data file or files
• Layout: The layout(s) (page.layout) that can be used with the sidenav
• File dependencies(s): If hard-coded, the data file(s) backing the sidenav
• Example: A link to a Stitch Docs page that uses the sidenav

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

Last updated: 20 July 2021