This site provides a machine-readable index at /llms.txt.

Skip to main content Skip to navigation

Reorder, rename, or hide entries in the sidebar

The sidebar is generated from folder layout and front matter. Each adjustment below is independent — pick the one that matches the change you need. To replace the sidebar component itself, see the extensibility guide for overriding DocSite components.

Assumptions

  • A Pennington DocSite has markdown under Content/<area>/ with at least one subfolder (the subfolder is what creates a sidebar group — see Work with front matter if not)
  • Pages use DocSiteFrontMatter or another type that implements IOrderable + ISectionable
  • The basics of order: and isDraft: are familiar — if not, start with Manage drafts, tags, and ordering

For a working reference, see examples/DocSiteKitchenSinkExample — Content/main/customize-sidebar.md exercises the same keys.

Options

Reorder pages within a section

Lower order: values sort earlier inside a section; ties break alphabetically on Title. Use 10/20/30 spacing so later inserts land between siblings without renumbering every file.

---
title: Install
order: 10
---

Backing symbol on the DocSite front-matter record:

/// <summary>Sort order within the containing section. Lower values appear first.</summary>
public int Order { get; init; } = int.MaxValue;

Promote a page to be the section landing

Name the file index.md inside the section subfolder (for example Content/main/widgets/index.md). Pennington routes it at the subfolder URL and NavigationBuilder surfaces it as the section's lead entry rather than a separate child. A low order: — typically 10 — sorts the entire section earlier, because the section's aggregate sort key is the minimum order: of its direct children.

---
title: Widgets
order: 10
---

The area-root landing follows the same pattern at one level up:

---
title: Kitchen Sink Docs
description: Wide-surface DocSite example that backs eighteen how-to pages.
order: 10
uid: kitchen-sink.main.index
---
  
# Kitchen Sink Docs
  
Welcome to the **DocSite Kitchen Sink** example. This site deliberately wires
every configurable DocSite surface referenced by the Pennington how-to index
so each recipe can point at a concrete file or `xmldocid` symbol.
  
## What's here
  
- Two content areas — **Main** and **API** — each with its own landing page.
- Two locales — English at the root, French under `/fr/`.
- One custom Mdazor component — `<FeatureCallout>` — demonstrated on the
  [UI components page](/main/ui-components-in-markdown).
- Alerts, tabbed code, diagrams, code annotations, cross-references,
  redirects, images, drafts, search-exclusion, and llms-txt-exclusion —
  each on its own page so the how-to can target it directly.
  
## Explore
  
- [Front matter](/main/front-matter/)
- [Drafts, tags, ordering](/main/drafts-tags-ordering/)
- [Customize the sidebar](/main/customize-sidebar/)
- [Images and assets](/main/images-and-assets/)
- [Tabbed code](/main/tabbed-code/)
- [Code annotations](/main/code-annotations/)
- [Alerts](/main/alerts/)
- [Diagrams](/main/diagrams/)
- [UI components in markdown](/main/ui-components-in-markdown/)
- [Cross-references](/main/cross-references-a/)
- [Linking](/main/linking/)
- [Redirects (source)](/main/redirect-source/)

Override the displayed section title

The sidebar section header comes from the folder name, with kebab-case converted to title case by NavigationBuilder (for example getting-started becomes "Getting Started"). Renaming the folder changes what the sidebar prints. The front-matter sectionLabel: key is separate — it sets the page-context label surfaced on NavigationInfo.SectionName for breadcrumbs and current-page context, not the sidebar group header.

---
title: Install
sectionLabel: Quick Start
---

Backing symbol for the front-matter key:

/// <summary>Section heading this page belongs under in navigation.</summary>
public string? SectionLabel { get; init; }

Hide a page from the sidebar

Set isDraft: true to keep the page compiled — so xref: links still resolve — while dropping it from the sidebar, the search index, and llms.txt. A page with redirectUrl: is also omitted from the sidebar regardless of other keys; the engine treats redirects as transport hops rather than content.

---
title: Work in progress
isDraft: true
---

Backing symbol on IFrontMatter (the draft key is not specific to DocSite):

/// <summary>True when the page is a draft and should be excluded from builds.</summary>
bool IsDraft => false;

Verify

  • Run dotnet run; reordered pages appear in ascending order: inside their section, and the section itself moves when its minimum-child order changes
  • The section subfolder's index.md lands at /<area>/<section>/ and renders as the section's lead entry in the sidebar
  • The drafted page's URL returns 404 and the entry is absent from the sidebar on reload
Previous
Next