Managing sections

Learn how to create and order sections on Braze Docs. To create, modify, or delete an individual page instead, see Pages. For general information about sections, see About content management.

Prerequisites

If you haven’t already, complete the steps for Contributing to Braze Docs.

Creating a section

Step 1: Create a directory and Markdown file

Open the relevant primary section or subsection, then create a directory and Markdown file for your new section.

1
2
3
4
5
6
braze-docs
└── _docs
    └── PRIMARY_SECTION 
        └── SUBSECTION 
            ├── NEW_DIRECTORY 
            └── NEW_FILE.md

Replace the following:

Your directory structure should be similar to the following:

1
2
3
4
5
6
braze-docs
└── _docs
    └── _developer_guide 
        └── platform_wide 
            ├── getting_started 
            └── getting_started.md

Step 2: Configure your section

When you create a new section, you can configure it with or without a landing page.

• With landing page: Use this method if your section needs a dedicated overview, such as a landing page for a “Getting started” section listing prerequisites and outlining the user journey.
• Without landing page: Use this method if your section does not need a dedicated overview. As stated in the Braze Docs Style Guide, content should always be useful, so avoid adding a landing page if it offers little useful content.

• with landing page
• without landing page

1
2
3
4
5
6
7
8
9
10
11
12
13
---
nav_title: NAV_TITLE
article_title: LANDING_PAGE_TITLE
description: SHORT_DESCRIPTION
---

# LANDING_PAGE_TITLE 

> SHORT_DESCRIPTION

## HEADING

CONTENT

1
2
3
4
---
nav_title: NAV_TITLE
config_only: true
---

1
2
3
4
5
6
---
nav_title: Getting started
page_order: 2
noindex: true
config_only: true
---

Step 3: Add additional pages

In your new directory, create a Markdown file for each page. To use the default page layout, use the template in Step 2. Your directory structure should be similar to the following:

1
2
3
4
5
6
7
8
braze-docs
└── _docs
    └── _developer_guide 
        └── platform_wide 
            ├── getting_started 
            │    ├── integrating_the_sdk.md 
            │    └── setting_up_push_notifications.md
            └── getting_started.md

When you’re finished adding content to each page, continue to Ordering a section.

Ordering a section

To order a section, open one of the Markdown files in that section and search for the page_order key within its YAML front matter.

1
2
3
---
page_order:
---

The page_order key represents a page’s relative-order in a section on the left-side navigation bar and can be set to any non-negative number (such as 0, 20, or 5.5). This means you’ll need to know the page_order for each Markdown file in the current directory, but not any other directory (including subdirectories).

Set the page_order key for each Markdown file in the current directory to any non-negative number. In the following example, page_order is set to 2.

1
2
3
4
5
6
---
nav_title: Subsection B
page_order: 2 
---

# Subsection B landing page

The output is similar to the following: