Sidebar

Dendron renders by default a sidebar that contains all of your notes that are partaking in the process of publishing. For more control on how the sidebar is displayed a config file can be provided. This page explains how this config file is to be configured.

To use sidebar on your Dendron site:

1. Define a file that exports a Sidebar
2. Pass the path to that file into sidebarPath

  publishing:
    sidebarPath: './sidebar.js'

Default Sidebar

If sidebarPath is unspecified, Dendron automatically generates a sidebar for you.

module.exports = [
  {
    type: 'autogenerated',
    id: 'root', // generate sidebar from the root
  },
],

The default config that autogenerates the sidebar, which you can also define explicitly.

Sidebar Object

At its crux the sidebar is a hierarchy of categories and note links,

type SidebarItem = SidebarItemCatetory | SidebarItemNote
type Sidebar = SidebarItem[]

For example:

module.exports = [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        {
          type: 'note',
          id: 'note1',
        },
      ],
    },
    {
      type: 'category',
      label: 'Dendron',
      link: { type: 'note', id: 'note2', }
      items: [
        {
          type: 'note',
          id: 'note3',
        },
        {
          type: 'note',
          id: 'note4',
        },
      ],
    },
    {
      type: 'note',
      id: 'some-note',
    },
]

This is a sidebar file that exports a sidebar object, which is a list of sidebar items. It has three top-level items: two categories and one note link. Within each category, there are a few note links as well.

For details on how the id attribute works checkout Referencing Note

Sidebar Item

We introduced two types of sidebar items: category and note. There is a third type: autogenerated which will be explained in detail later.

• Autogenerated : autogenerates this sidebar item from the specified domainNote
• Note: link to a note page
• Category: create a hierarchy of sidebar items

Note

Use the note type to link to a note page and assign that note to a sidebar:

type SidebarItemNote = {
  type: 'note';
  id: string;
  label: string; // Sidebar label text
}

Example:

module.exports = [
  {
    type: 'note',
    id: 'note1', // `id` or `fname` of the note
    label: 'Getting started', // sidebar label
  },
]

Category

Use the category type to create a hierarchy of sidebar items.

type SidebarItemCategoryLinkNote = { type: 'note', id: string }
type SidebarItemCategory = {
  type: 'category';
  id: string;
  label: string; // Sidebar label text
  items: SidebarItem[]; // Array of sidebar items
  link: SidebarItemCategoryLinkNote
}

Example:

module.exports = [
  {
    type: 'category',
    label: 'Guides',
    link: { type: 'note',id: 'note1' },
    items: [
      {
        type: 'category',
        label: 'Docs',
        items: [{
          type: 'note',
          id: 'note2'
        }],
      },
    ],
  },
]

Category links

With category links, clicking on a category can navigate you to another page.

module.exports = [
  {
    type: 'category',
    label: 'Guides',
    link: {type: 'note', id: 'introduction'}, // Clicking on menu item labeled 'Guides' would  navigation to 'introduction'
    items: [/*imagine some items here, or empty*/],
  },
]

Autogenerated

Dendron can generate a sidebar automatically from your notes (this is the default behavior). Each hierarchy creates a sidebar category, and each nested note a note link.

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  id: string | 'root'; // Source hierarchy to generate the sidebar slice from
};

Example

module.exports = [
  {
    type: 'autogenerated',
    id: 'root',
  },
]

The autogenerated item is converted into a sidebar slice, which is a nested list of items of type note or category. The id field specifies from which hierarchy a sidebar slice should be created.

For details on how the id attribute works checkout Referencing Note

languages.python.data.bool.md
languages.python.data.integer.md
languages.python.data.md
languages.python.data.string.md
languages.python.data.string.memory.md
languages.python.machine-learning.md
languages.python.machine-learning.pandas.md
languages.python.machine-learning.scipy.md

module.exports = [
  {
    type: 'category',
    label: 'Intro',
    items: [
      {
        type: 'autogenerated',
        id: 'languages.python'
      },
    ]
  }
]

module.exports = [
  {
    type: "category",
    label: "Intro",
    items: [
      {
        type: "category",
        label: "Data",
        items: [
          {
            type: "note",
            id: "ml2iUxT9ljJMXSC4b1yzo",
            label: "Bool"
          },
          {
            type: "note",
            id: "6tG2OW2u9mYlzf9F09u4j",
            label: "Integer"
          },
          {
            type: "category",
            label: "String",
            items: [
              {
                type: "note",
                id: "p9peEtJdzui5qJ8z4rfrt",
                label: "Memory"
              }
            ],
            link: {
              type: "note",
              id: "LmfREuriowlRnQ4BTCrUa"
            }
          }
        ],
        link: {
          type: "note",
          id: "bDBYPZYlhiZUzqvnW3FGJ"
        }
      },
      {
        type: "category",
        label: "Machine Learning",
        items: [
          {
            type: "note",
            id: "qp9GpwdH7mWiYKDhR1aPN",
            label: "Pandas"
          },
          {
            type: "note",
            id: "f4qdTnePkV8rA1uu9gSyJ",
            label: "Scipy"
          }
        ],
        link: {
          type: "note",
          id: "FIHLF81wxYDFKq0d2PPoI"
        }
      }
    ],
  },
]

Sorting

By default autogenerated items are sorted alphabetically. This can be changed by the following frontmatter attributes:

• sort_order
  • type: reverse | normal;
  • default: normal
  • required: false

Currently the only optionality available is sort_order. In the future we might implement sort_by.

Referencing note

The sidebarItem's id attribute is used to reference a note or hierarchy. A note can be referenced by two identifiers. The filename of the note (without the extension) fname which is only unique inside each vault or the note's global identifier id.

This is checked in the following way:

1. Find a note by note's id attribute.
2. Find a note by note's fname attribute and relying on duplicateNoteBehavior when multiple notes are found

Complex sidebar example

const sidebars = [
  {
    type: "note",
    label: "Introduction",
    id: "dendron",
  },
  {
    type: "note",
    label: "Principles",
    id: "dendron.principles",
  },
  {
    type: 'category',
    label: 'Concepts',
    link: {
      type: 'note',
      id: 'dendron.concepts',
    },
    items: [{
      type: 'autogenerated',
      id: 'dendron.concepts'
    }]
  },
  {
    type: 'category',
    label: 'Getting Started',
    link: {
      type: 'note',
      id: 'dendron.tutorial',
    },
    items: [{
      type: 'autogenerated',
      id: 'dendron.tutorial'
    }]
  },
  {
    type: 'category',
    label: 'Guides',
    link: {
      type: 'note',
      id: 'dendron.guides',
    },
    items: [{
      type: 'category',
      label: 'Workflows',
      link: { type: 'note', id: 'dendron.guides.workflows' },
      items: [{
        type: 'autogenerated',
        id: 'dendron.guides.workflows'
      }],
    }, {
      type: 'note',
      label: 'Best practices',
      id: 'dendron.guides.best-practices'
    }, {
      type: 'note',
      label: 'Migration',
      id: 'dendron.guides.migration'
    }, {
      type: 'note',
      label: 'Tips',
      id: 'dendron.guides.tips'
    }]
  },
  {
    type: "note",
    label: "Cheat sheet",
    id: "dendron.cheatsheet",
  },
  {
    type: 'category',
    label: 'Reference',
    link: {
      type: 'note',
      id: 'dendron.ref',
    },
    items: [{
      type: 'autogenerated',
      id: 'dendron.ref'
    }]
  }
]

• Changelog
• 0.114
• Publish
• Publishing Features
• Sidebar