Location

Sidebar are defined using YAML files stored in _data/sidebars/. For example, the sidebar used for this page is _data/sidebars/unidata_sidebar.yml. If you add a new sidebar, you will need to make sure to add it to the _config.yml file at the top level of the docs directory.

Syntax

The Sidebar will be assigned a title based on the following, if defined (in order of precedence):

  • The value of the product key associated with the first title key under entries in the sidebar yaml file
  • The value of the first title key under entries in the sidebar yaml file
  • The value of site_title defined in _config.yml

If version information is found, it will be added to the sidebar title based on the following (in order of precedence)

  • The value of the version key associated with the first title key under entries in the sidebar yaml file
  • The value of docset_version defined in _config.yml

If none of these are defined, the sidebar will have a label of “Untitled Sidebar”. The sidebar used for this page looks like the following:

entries:
  - title:
    folders:
      - title:
        output: pdf
        type: frontmatter
        folderitems:
          - title:
            url: /titlepage
            output: pdf
            type: frontmatter
          - title:
            url: /tocpage
            output: pdf
            type: frontmatter

      - title: Getting Started
        output: web, pdf
        folderitems:
          - title: Working on the theme
            url: /index.html
            output: web, pdf

      - title: Markdown
        output: web, pdf
        folderitems:
          - title: Overview
            url: /overview.html
            output: web, pdf
          - title: Headings
            url: /headings.html
            output: web, pdf
          - title: Links
            url: /links.html
            output: web, pdf
          - title: Images
            url: /images.html
            output: web, pdf
          - title: Files
            url: /files.html
            output: web, pdf
          - title: Highlight Blocks
            url: /highlight_blocks.html
            output: web, pdf
          - title: Indentation
            url: /indentation.html
            output: web, pdf
      - title: Theme
        output: web, pdf
        folderitems:
          - title: Upstream Theme Overview
            url: /upstream_theme.html
            output: web, pdf
          - title: Front Matter
            url: /front_matter.html
            output: web, pdf
          - title: Sidebars
            url: /sidebars.html
            output: web, pdf
          - title: Table Of Contents
            url: /toc.html
            output: web, pdf
            subfolders:
              - title: Unidata Jekyll Plugins
                output: web, pdf
                subfolderitems:
                - title: Sharing content between .md files
                  url: /sharing_content.html
                  output: web, pdf
                - title: Include code snippets
                  url: /code_snippets.html
                  output: web, pdf

      - title: Style
        output: web, pdf
        folderitems:
          - title: Style guide
            url: /style.html
            output: web, pdf

If you want the title of your sidebar to link to a page other than index.html, use the sidebar_url key associated with the first title key under entries in the sidebar yaml file, like so:

entries:
- title:
  sidebar_url: otherpage.html
  ...

Right Sidebars (In-Page Navigation)

Right sidebars, used for in-page navigation, can be enbled via the Table Of Contents.