sitemd.cc

Sidebar

Pages that belong to a group with a sidebar location get a two-column layout automatically. The sidebar shows the group's items as a navigation list with the current page highlighted.

How does a page get a sidebar?

Add a sidebar location to a group in settings/groups.md, then make pages members of that group:

# settings/groups.md
groups:
  - name: docs
    locations:
      - sidebar:
          - group: docs
    items:
      - Getting Started: /docs/getting-started
      - Themes: /docs/themes

# pages/docs/themes.md frontmatter
groupMember:
  - docs

Every page with groupMember: [docs] now shows the docs sidebar. Override this per-page with sidebarGroupShown:

sidebarGroupShown: docs    # force this group's sidebar
sidebarGroupShown: none    # suppress sidebar entirely

See Groups for the full location syntax, including targeting specific pages by file path.

Per-page sidebar

Sometimes you want a custom sidebar on a single page without involving groups at all — a long doc page that needs a table of contents, a landing page with curated jump links, or a one-off layout. Use the sidebar frontmatter key on the page itself.

Explicit list

Declare items inline. Same Label: /url syntax as nav and groups, with full support for modifiers like +newtab:

---
title: My Page
sidebar:
  - Overview: /docs/overview
  - GitHub: https://github.com/sitemd-cc/sitemd +newtab
  - API: /docs/api
    - Authentication: #authentication
    - Rate Limits: #rate-limits
---

Top-level items are sidebar links. Indent a sub-item with two extra spaces to attach it as an anchor under its parent (rendered as an expandable sub-list, just like group anchors).

For long pages where the sidebar should mirror the page's own structure, use the self shortcut:

---
title: My Long Doc
sidebar: self
---

On the next build, sitemd walks the page's heading hierarchy and rewrites the frontmatter into the equivalent explicit nested list:

Anchors that sit immediately before a heading (the common alt-id pattern, e.g. {#short-id} directly above ## A long heading title) are skipped, so you don't get a duplicate entry for the same destination.

For a page with two sections, each with sub-sections and one inline anchor, the writeback looks like:

sidebar:
  - Installation: /docs/my-long-doc#installation
    - Quick start: /docs/my-long-doc#quick-start
    - From source: /docs/my-long-doc#from-source
  - Configuration: /docs/my-long-doc#configuration
    - Theme: /docs/my-long-doc#theme
    - Advanced options: /docs/my-long-doc#advanced-options

Because sidebar: self expands into the explicit list, you can edit, reorder, or remove entries afterward — the shortcut is a one-time scaffold, not a dynamic binding.

Suppress an inherited sidebar

If a page is a member of a group with a sidebar location but you don't want the sidebar on that one page, set:

sidebar: none

This is equivalent to sidebarGroupShown: none and takes precedence over any group membership.

Precedence

When both a per-page sidebar: and group-derived sidebar would apply, the per-page sidebar: always wins. Group-driven sidebars only render when no sidebar: is set in the page frontmatter.

Per-page sidebars get the same search button, active-link highlighting, and anchor scroll behavior as group sidebars.

The sidebar includes a scoped search bar. Click the magnifying glass icon or start typing to search within the current group's pages and the current page's headings.

Results are split into two sections:

Section What it searches
This page Headings on the current page that match your query
Other pages Pages in the same group, ranked by title and content match

Typo tolerance applies to titles and headings only — a misspelled query like colur will still surface a page whose title or heading contains "color". Body text is matched as exact substrings, so a typo won't fuzzy-match against page bodies.

Selecting a result navigates to that page or heading and highlights the matched text. Use arrow keys to navigate results and Enter to select.

Site-wide search is always available via ⌘K (Mac) or Ctrl+K (Windows/Linux), independent of the sidebar.

Anchor navigation

Sidebar items can have nested anchors that link to sections within a page. These appear as an expandable sub-list below the parent link:

# settings/groups.md
items:
  - Getting Started: /docs/getting-started
    - Install: #install
    - Connect Your Agent: #connect-your-agent
    - Build and Preview: #build-and-preview

Each anchor is a - Label: #heading-id entry indented under its parent item. The heading ID matches a ## heading on that page — ## Install becomes #install.

The active page's anchors expand automatically. Click the chevron to expand or collapse any section. As you navigate between anchor links, the active anchor is highlighted in the sidebar.

Default display

Anchors are collapsed by default. To show all anchors expanded on load:

groups:
  - name: docs
    anchorsDisplay: expanded
Value Behavior
collapsed Anchors hidden until expanded. Active page always expands automatically.
expanded All anchors visible on load.

See Groups — Sidebar Anchors for details on finding heading IDs.

How does the sidebar work on mobile?

On screens under 768px, the sidebar content moves into the hamburger menu. Open the menu and you'll see your site navigation at the top, followed by an "In this section" block containing the sidebar search and page links.

This means one tap opens everything — site nav, section nav, and search. Clicking any link in the menu closes it automatically, including anchor links that scroll within the current page.

The sidebar is not a separate toggle on mobile. It shares the same hamburger menu as the header navigation.

Scrolling

On desktop, the sidebar is sticky — it stays visible as you scroll the page. When the sidebar content is taller than the viewport, a scrollbar appears so you can scroll the sidebar independently.

The scrollbar only renders when needed. Short sidebars with few items show no scrollbar. As you expand anchor sections or resize the browser, the scrollbar appears or disappears dynamically.

The active page link scrolls into view automatically on page load, so you always see where you are even in long sidebars.