This article walks through the options for adding metadata to Docs pages. We optimize our search based on page type and other bits of metadata, including: yaml tags and page types (based on templates).
The content tags listed on this page are currently a work in progress and cannot be applied to pages without causing errors. Check back later for the final version, when these can be safely applied! Note that you can currently use the
platform content tag.
These are independent. If you need to see additional optional YAML content based on “Layout”, check out the templates and layouts (TBD) breakdowns.
A note on capitalization…
Leave all tag values (except for the content for the
description tag) lowercase. This will ensure consistency. We may change this in the future, but for now, lowercase is better and easier to mass search and replace in the event of a formatting update.
These will automatically change the layout or function of a page.
|YAML Content Tag||Description||Required?||Data Type||Available Values|
||This is the title of the article that will appear in the left navigation of the Docs site. Encapsulate in quotes.||Yes, unless page is
||String.||Any - the title of a page is up to you. We recommend less than 30 characters with spaces.|
||This is the order in which the article will appear in the left navigation of the Docs site.||Yes, unless page is hidden.||Integer.||Any number (including multiple decimals) between
||Notes whether or not the page will be visible in the left navigation bar. Setting this to
||No.||Boolean.||You may choose between
||Whether or not a page will act as a page or as a category in the left navigation panel. Defaults to
||No.||Boolean.||You may choose between
||Sets the page’s url. For example:
||No, unless page is
||String.||Any - this URL is up to you. Encapsulate in slashes (
||Sets specific features on the page that align with developed layouts. Defaults is a regular page.||No.||String.||If you do not set this, it will default to a regular content page. You may choose between:
||Determines whether the Table of Contents on the right side of the page is included or not.||No.||Boolean.||You may choose between
||Determines whether the article will show in Algolia and Google Searches. Defaults to
These will assist in external and internal SEO, informing page content and formatting, and other content-based structure.
|YAML Content Tag||Description||Required?||Exclusive or can multiple be used?||Data Type||Available Values|
||Description of the page that will show in online searches. Encapsulate in quotes.||Yes.||Exclusive up to 160 characters.||String.||Any - the page description of a page is up to you. We recommend less than 3 sentences.
||Type of page, determined by page templates. Inform formatting and content.||Yes.||Exclusive; only one can be used per page.||String.||See Page Types.|
||Notes which platforms (iOS, Android, etc.) the article is associated with.||No, unless on a Dev Guide page.||Multiple values can be used.||String.||Any of the platforms Braze integrates on:
||Notes which messaging channels (push, in-app messages, etc.) the article is associated with.||No, unless the content mentions a specific channel or channels.||Multiple values can be used.||String.||Any of the messaging channels Braze sends to:
||Notes which engagement tools (Canvas, campaigns, etc.) the article is associated with.||Yes.||Multiple values can be used.||String.||Any of Braze’s tools:
Multiple Tag Values
Sometimes, you may find that a content tag for a page could be categorized with multiple values (as in, an article might talk about both Canvas and campaigns, or cover a custom integration for both Android and iOS).
You can format that like this:
1 2 3 4 5 6 7 key: - string1 - string2 - string3 - string4 - string5 - string6
Note that there can only be a single
page_type value for page. A page cannot be both a
reference and a
glossary. The different page types exist to narrow the scope and purpose of each article.
The top of every markdown page should begin with a section of yaml to define the page.
1 2 3 4 5 6 7 8 9 10 --- nav_title: "Docs Metadata" page_order: 0 description: "This page walks through the options for adding metadata to Docs pages. We optimize our search based on page type and other bits of metadata. This is a great resource for contributors via our GitHub page." page_type: reference tool: - docs - dashboard ---
To apply these, be sure your yaml parameter for page types is:
Page Type Tag
||Page provides a searchable description of certain terms or elements (metrics, words to know, API Endpoints, etc.)||API or Code Glossary
||A troubleshooting or “options” article that walks users through a solution to an issue or through steps to resolving or narrowing down an issue.||Help Article
||An article that explains a concept and contains specific information about technical processes and product content. (Canvas Steps, Segmentation, specific Product Features etc.).||Reference Article with Video
||A general walkthrough of an instructional concept. Should contain practical knowledge. Focuses on a single topic (like, how to create a campaign, how to create a canvas, etc.) Goal or Task-Oriented Article that walks step-by-step through solving a specific issue (How to target specific users, how to segment based on location, etc.).||Tutorial Article with Video
Use Case Article with Video
Use Case Article
||Page provides a selection of options within a certain section, as well as a description or overview of said section.||Single Section Landing Page using FA Icons
Single Section Landing Page using Images
Multi-Section Landing Page using FA Icons
Multi-Section Landing Page using Images
||A page that combines many of the preceding page types into a single page. These pages describe a partner, the benefits of that partner, how to integrate that partner, then how to use that integration and any best practices associated with that usage.||Partner Page with Video
|Updates and Release Notes
||A page that lists updates to a product or SDK in succession. A single update on a larger page or a page about a new feature would not count as an
||See Release Notes Pages and SDK Changelogs pages.|
Potential Page Type: Best Practices