How to Create Sections

This guide shows you how to create sections in the handbook for different scenarios.

Create a Basic Section

Goal: Add a new top-level section to the handbook.

Create the section directory

Create the section file

Add frontmatter and content

Create a Nested Section

Goal: Add a subsection inside an existing section.

Create the nested directory

Create the section file

Add frontmatter

Create a Section with Collapsed Sidebar

Goal: Create a section that starts collapsed to keep navigation clean. Create your section as normal.

Add the sidebar field to frontmatter

When to use:

  • Sections with many pages (5+)
  • Lower-priority content
  • Keeping main navigation clean

Create a Section with Expanded Sidebar

Goal: Create a section that shows its pages immediately.

Add the sidebar field set to true:

When to use:

  • Important sections users access frequently
  • Sections with only 2-3 pages
  • Getting started or installation sections

Reorganize Section Order

Goal: Change where a section appears in navigation.

Open the section’s _index.md file

Locate and open the section’s _index.md

Change the weight value

Convert a Page to a Section

Goal: Turn a single page into a section with multiple pages.

Rename the page file

Add child pages

Delete a Section

Goal: Remove a section and all its pages.

Backup first (optional but recommended):

Delete the directory:

Section is completely removed.

Warning: This cannot be undone without git history or backups.

Common Patterns

Documentation Section Structure

Related Guides

Edit this page on GitLab ↗