About content management

This is an overview for how content is managed on Braze Docs. To learn more about a specific topic, choose the dedicated topic page in the navigation.

Methodology

Braze Docs is managed using docs-as-code, a method for managing documentation that mirrors the software development lifecycle by using a version control system. Braze Docs uses the Git version control system, which allows contributors to work on the same piece of documentation without overwriting each other’s work. For more information, see About version control and Git.

Site generator

Braze Docs is built using Jekyll, a popular static-site generator that allows content files and design files to be stored in separate directories, such as _docs for content files and assets for design files. When the site is built, Jekyll intelligently merges each file and stores them as XML and HTML data in the _site directory. For more information, see Jekyll Directory Structure.

As a contributor, you’ll primarily work within the following directories.

Pages

Each page on Braze Docs is written in Markdown syntax and stored as a Markdown file using the .md file extension. At the top of each Markdown file, YAML front matter is used to add hidden metadata for each page.

1
2
3
4
5
---
METADATA_KEY: METADATA_VALUE
---

# CONTENT

Replace the following.

• example input
• example output

1
2
3
4
5
6
7
8
9
10
11
---
nav_title: Contributing to Braze Docs
article: Contributing to Braze Docs
description: "Here's what you need to start contributing to Braze Docs!"
page_order: 0
search_tag: Contributing
---

# Contributing to Braze Docs

> Thanks for contributing to Braze Docs! Every Tuesday and Thursday, we merge community contributions and deploy them to Braze Docs. Use this guide to get your changes merged during our next deployment.

Images

Images are stored as PNG files inside assets/img. The structure of the img directory does not need to match the structure of Braze Docs; however, it’s best to group related images together into subdirectories.

Each image can be linked to one or more pages using the following syntax.

1
![ALT_TEXT.]({% image_buster /assets/img/DIRECTORY/IMAGE.png %})

Replace the following.

Your in-line image should be similar to the following:

1
![The form for creating a new pull request on GitHub.]({% image_buster /assets/img/contributing/getting_started/github_pull_request.png %})

Sections

Braze Docs is organized into primary sections and subsections.

Primary sections

The primary sections on Braze Docs are:

• Braze Docs Home
• User Guide
• Developer Guide
• Braze API Guide
• Technology Partners
• Braze Help
• Contributing to Braze Docs

Other than Contributing to Braze Docs, these primary sections can be accessed on the site header from any page on Braze Docs.

Each primary section is built using Jekyll collections, which allows related content to be grouped together for easy management. Keep in mind, while all primary sections are collections, not all collections are primary sections. You can find the full list of Braze Docs collections in the Jekyll configuration file, _config.yml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
collections:
  home:
    title: Documentation
    output: true
    default_nav_url: ''
    page_order: 1
  user_guide:
    title: User Guide
    output: true
    default_nav_url: introduction/
    page_order: 2
  developer_guide:
    title: Developer Guide
    output: true
    default_nav_url: home/
    page_order: 3
  api:
    title: API
    output: true
    default_nav_url: home/
    page_order: 4
  partners:
    title: Technology Partners
    output: true
    default_nav_url: home/
    page_order: 5
  help:
    title: Help
    output: true
    default_nav_url: home/
    page_order: 6
  contributing:
    output: true
    default_nav_url: contributing/
  hidden: # Hidden pages not directly linked via navigation
    title: Braze
    output: true
    hidden: true
  docs_pages: # Site specific pages. ie main redirects and search
    title: Braze
    output: true
    hidden: true

Each collection listed represents a directory within the _docs directory.

1
2
3
4
5
6
7
8
9
10
11
braze-docs
└── _docs
    ├── _api
    ├── _contributing
    ├── _developer_guide
    ├── _docs_pages
    ├── _help
    ├── _hidden
    ├── _home
    ├── _partners
    └── _user_guide

The landing page for each primary section is a standard Markdown file with the page_order: key set to 0.

• example input
• example output

1
2
3
4
5
6
7
---
page_order: 0
nav_title: Home
article_title: Braze User Guide
layout: user_guide
user_top_header: "Braze User Guide"
---

Subsections

All primary sections on Braze Docs contain one or more subsection, each representing an expandable item on the left-side navigation.

Unlike primary sections, subsections can be configured with or without a landing page. Subsections without landing pages are helpful for organizing related content together while minimizing the number of non-useful pages in Braze Docs. Whether a subsection is configured with or without a landing page, all subsections represent both a directory and Markdown file in the repository. For an example, see the following.

1
2
3
4
5
6
7
8
9
10
11
braze-docs
└── _docs
    └── _primary_section
        ├── subsection_a
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_b
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_a.md # not configured as a landing page
        └── subsection_b.md # configured as a landing page  

In the _primary_section directory, subsection_a is not configured with a landing page, while subsection_b is configured with a landing page. In the following example, subsection_a.md has config_only: set to true, which prevents this page from being rendered as a landing page.

• example input
• example output

1
2
3
4
5
---
nav_title: Subsection A
page_order: 0
config_only: true
---

However, subsection_b.md doesn’t use the config_only: key, so this page is rendered as a landing page.

• example input
• example output

1
2
3
4
---
nav_title: Subsection B
page_order: 0
---

Cross-references

A cross-reference is when one page on Braze Docs links to another page on Braze Docs. Due to certain site requirements, Braze Docs doesn’t support standard Markdown syntax for cross-reference links, so we created one using Liquid.

1
[LINK_TEXT]({{site.baseurl}}/SHORT_URL)

Replace the following:

Your cross-reference link should be similar to the following:

1
Before continuing, [create your SSH token]({{site.baseurl}}/docs/developer_guide/platform_wide/sdk_authentication).

Content reuse

Jekyll offers the ability to reuse written content across the docs using the include tag. Includes are located in the _includes directory and can be written in Markdown or HTML syntax.

1
{% multi_lang_include RELATIVE_PATH/FILE %}

Replace the following:

• example input
• example output

1
2
3
4
5
# Pages

> Learn how to create, modify, and remove pages on Braze Docs.

{% multi_lang_include contributing/prerequisites.md %}

Layouts

By default, Jekyll uses the default.html layout in the _layouts directory to build each page on Braze Docs. However, different layouts can be used by assigning the layout to the layout: key in the YAML front matter.

1
2
3
---
layout: LAYOUT_VALUE
---

Replace LAYOUT_VALUE with the name of the layout file and the file extension removed.

• example input
• example output

1
2
3
braze-docs
└── _layouts
    └── api_page.html

1
2
3
---
layout: api_page
---

URLs

URLs on Braze Docs always match the directory structure within the docs repository. Given the following example file tree, the URL for page_a.md would be https://www.braze.com/docs/primary_section/subsection_a/page_a.

1
2
3
4
5
braze-docs
└── _docs
    └── _primary_section
        └── subsection_a
            └── page_a.md

This includes URLs for pages located in a subsection with config_only: set to true. Even though config_only subsections aren’t rendered as pages, the subsection’s directory name is still used to generate the URLs for pages in that directory. For an example, see the following.

1
2
3
4
5
6
7
8
9
10
11
braze-docs
└── _docs
    └── _primary_section
        ├── subsection_a
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_b
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_a.md # not configured as a landing page
        └── subsection_b.md # configured as a landing page  

• subsection a
• subsection b

1
2
3
4
5
---
nav_title: Subsection A
page_order: 1 
config_only: true
---

1
2
3
Subsection A URL: N/A
Page A URL: https://www.braze.com/docs/primary_section/subsection_a/page_a
Page B URL: https://www.braze.com/docs/primary_section/subsection_a/page_b

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

1
2
3
Subesction B URL: https://www.braze.com/docs/primary_section/subsection_b
Page A URL: https://www.braze.com/docs/primary_section/subsection_b/page_a
Page B URL: https://www.braze.com/docs/primary_section/subsection_b/page_b