Skip to content

Your first contribution

If you’re new to docs-as-code or Braze Docs, start with this step-by-step tutorial. If you’re an experienced contributor, see About content management instead.

When you’re finished with this tutorial, you’ll be able to:

  • Navigate the Braze Docs GitHub repository
  • Make changes using the GitHub website or your local environment
  • Create pull requests (PRs)
  • Preview your changes in a test site
  • Request a review from the Braze Docs team

Prerequisites

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

Step 1: Explore the GitHub repository

The Braze Docs GitHub repository hosts the source files for Braze Docs. Take a few minutes to explore the repository, even if you don’t understand everything yet. Over time, you’ll become more familiar.

The Braze Docs GitHub repository homepage.

Step 2: Make a change

Now that you’re a little familiar with the docs repository, you’re ready to start making changes. First, open Braze Docs and find a simple change you’d like to make, then decide how you’d like to make it:

  • Using GitHub (Simple): For small, single-document changes, you can make changes directly from the GitHub website.
  • Using your local environment (Advanced): For complex or multi-document changes, you’ll need to make changes from your local environment. This is the recommended method.

In the Braze Docs GitHub repository, select _docs.

The Braze Docs GitHub repository homepage with the '_docs' folder highlighted in the file tree.

Each page’s URL on Braze Docs reflects the repository’s directory structure. Use your page’s URL to find its corresponding Markdown file in the _docs directory. For example, the Markdown file for braze.com/contributing/home can be found in _docs > _contributing > home.md.

The home page for the "Contributing" section on Braze Docs.

Select Edit this file, then make your changes using Markdown formatting.

An example page on Braze Docs showing "Edit this file".

When you’re finished, select Commit changes.

The Braze Docs GitHub repository showing "Commit changes" after editing a file.

In the next window, select Propose changes.

The "Propose changes" window after selecting "Commit changes" in GitHub.

Most modern text editors (such as VS Code and Intellij IDEA) offer an in-app terminal for running commands and interacting with your project files. Open your text editor, then open your text editor’s in-app terminal.

Intellij IDEA with the in-app terminal open.

In the terminal, open the braze-docs directory.

1

cd ~/PATH_TO_REPOSITORY

Replace PATH_TO_REPOSITORY with the location you saved the braze-docs repository when you set up your environment. Your command should be similar to the following:

1

cd ~/braze/braze-docs

Check if you’re in the braze-docs directory, then check your Git status.

1
2

pwd
git status

In the docs repository, the develop branch reflects the most up-to-date version of Braze Docs. Check out the develop branch and pull the latest updates into your local environment.

1
2

git checkout develop
git pull

When making changes to the docs, you’ll always create a new branch. Use git branch along with the -b flag to create a new branch.

1

git checkout -b BRANCH_NAME

Replace BRANCH_NAME with a short, non-space-separated description of your changes. Your command should be similar to the following:

1
2

$ git checkout -b fixing-typo-in-metadata
Switched to a new branch 'fixing-typo-in-metadata'

In your text editor, open the document you want to change, then make your changes using Markdown formatting.

When you’re finished, save your changes, then select the terminal and check your Git status. The output is similar to the following:

1
2
3
4
5
6
7
8

$ git status
On branch fixing-typo-in-metadata
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   _docs/_home/metadata.md

no changes added to commit (use "git add" and/or "git commit -a")

Use git add to tell Git which changes you want to stage for your commit. The following command shows two options:

  • Left side of pipe: Add all of your changed files using --all.
  • Right side of pipe: Add an individual file by replacing PATH_TO_FILE with the relative path to your changed file.
1

git add {--all|PATH_TO_FILE}

Use git commit with the -m flag to create your commit along with a short description (or message).

1

git commit -m "COMMIT_MESSAGE"

Replace COMMIT_MESSAGE with a short sentence describing your changes. Your command should be similar to the following:

1
2
3

$ git commit -m "Fixing a typo in the recommended software doc"
[fixing-typo-in-recommended-software 8b05e34] Fixing a typo in the recommended software doc.
 1 file changed, 1 insertion(+), 1 deletion(-)

Finally, push your changes to the Braze Docs GitHub repository.

1

git push -u origin BRANCH_NAME

Replace BRANCH_NAME with the name of your branch. The output is similar to the following:

1
2
3
4
5
6

$ git push -u origin fixing-typo-in-recommended-software
Enumerating objects: 14, done.
...
To github.com:braze-inc/braze-docs.git
 * [new branch]      fixing-typo-in-recommended-software -> fixing-typo-in-recommended-software
branch 'fixing-typo-in-recommended-software' set up to track 'origin/fixing-typo-in-recommended-software'.

Step 3: Create a pull request (PR)

If you are not already there, go back to the repository homepage and select Compare & pull request.

The Braze Docs GitHub repository homepage showing "Open pull request".

In the PR description, you’ll see Markdown comments similar to the following:

1

<!-- This is a Markdown comment. -->

These comments will guide you through your PR description. When you’re finished, select the pull request dropdown, then select Draft pull request.

An example pull request showing "Draft pull request".

Finally, check Allow edits and access to secrets from maintainers. This will let the Braze Docs team make style or formatting changes to your content during their review later.

A Pull Request showing the allow edits from maintainers checkbox.

Step 4: Review your work

Create your content by following the Braze Docs Style Guide and reviewing your work in a site preview. If you need to make additional changes, see Make additional changes. Otherwise, you can request a review from the Braze Docs team.

In a PR comment, tag @braze-inc/docs-team to request a site preview.

An example comment tagging the Braze Docs team to request a site preview.

To open the site preview, select View deployment.

An example pull request showing the "View deployment" button generated by the Vercel bot.

In the terminal, use the rake command start a local server.

1
2

cd ~/braze-docs
rake

The output will be similar to the following:

1
2
3
4
5
6
7
8
9

== Sinatra (v3.0.4) has taken the stage on 4000 for development with backup from Puma
Puma starting in single mode...
* Puma version: 6.3.1 (ruby 3.2.2-p225) ("Mugi No Toki Itaru")
*  Min threads: 8
*  Max threads: 32
*  Environment: development
*          PID: 16158
* Listening on http://127.0.0.1:4000
...

By default, your site preview will be generated on localhost http://127.0.0.1:4000. To open your site preview, open the link in your web browser.

An example site preview running in a web browser.

To stop your local server, reopen the terminal and press Control + C.

Step 5: Request a review

If you’re ready for a member of the Braze Docs team to review your work, select Ready for review.

An example pull request showing "Ready for review".

In the Reviewers field, type braze-inc/docs-team. Select the team name and press Esc or click out of the dropdown to confirm your selection.

An example pull request with "docs-team" added as the reviewer.

If the docs team requests additional changes after their review, you’ll be notified per your GitHub notification settings. Otherwise, the docs team will approve and merge your changes.

Approved contributions will be deployed on the next Tuesday or Thursday. Be sure to check out Braze Docs to see your hard work. Thanks for contributing!

Step 6: Make additional changes (optional)

After you or a member of the Braze Docs team reviews your work, you may need to make additional changes to your PR. You can do so using your local environment or GitHub.

In your PR, select Files changed, then locate the file you’d like to update and select Show options > Edit file.

The "Files changed" section in an example pull request showing "Edit file".

When you’re finished, select Commit changes.

A file from an example pull request showing "Commit changes" after editing.

Select Commit directly to the BRANCH_NAME branch > Commit changes, where BRANCH_NAME is the name of your branch.

The "Commit changes" option after choosing "Commit directly to BRANCH_NAME branch.

When you’re finished, request a review.

In your PR, select Copy next to your branch name.

An example pull request with the "Copy" icon shown next to the branch name.

In your text editor’s terminal, checkout your branch and pull the latest updates from the remote branch in GitHub.

1

git checkout BRANCH_NAME && git pull

Replace BRANCH_NAME with the branch name you copied to your clipboard. The output is similar to the following:

1
2
3

$ git checkout fixing-typo-in-metadata  && git pull
Switched to branch 'fixing-typo-in-metadata'
Your branch is up to date with 'origin/fixing-typo-in-metadata'.

In your text editor, open the document you want to change, then repeat the repeat the steps you completed earlier during Step 2: Make a change.

Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!