Skip to content

local_environment.md

Latest commit

 

History

History
165 lines (128 loc) · 6.71 KB

local_environment.md

File metadata and controls

165 lines (128 loc) · 6.71 KB
Raw

Set up your local environment

Learn how to set up your local Braze Docs environment, so you can make complex or multi-page changes.

Setting up your local environment

Step 1: Get the required software

At a minimum, you need a terminal, a text editor, and a ruby version manager. If you're not sure where to start, see the following.

Type Product Description
Git GUI GitHub Desktop A graphical user interface (GUI) you can use to run Git commands, instead of typing commands in the terminal.
Terminal Wezterm A terminal emulator that allows you to run commands and interact with the Braze Docs repository from the commandline. If you're using a Windows operating system, you'll also need to install Windows Subsystem for Linux (WSL).
Terminal extension Windows Subsystem for Linux (WSL)* WSL lets you install a Linux subsystem and run Unix-like commands on your Windows operating system. If you're contributing from a Windows operating system, we recommend installing WSL, so you can use any Unix-like command mentioned in the docs.

* Only available for Windows.
Package manager Homebrew A package manager that allows you to install and manage the various command-line interface (CLI) tools used for contributing to Braze Docs.
Tool manager asdf A tool manager for installing and switching between multiple versions of Node.js. You can install this during set up later.
Ruby version manager rbenv A Ruby version manager that allows you to install and manage the required Ruby version for Braze Docs when you're setting up your local environment. To use a different Ruby version manager, see Ruby's supported version managers.
Text editor Visual Studio Code (VS Code) A full-featured text editor by Microsoft that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins:
Text editor Intellij's IDEA Community Edition A full-featured text editor by Intellij that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins:

Note

As of writing, all software is free of cost. If you find that a product is no longer free, ask in #ask-docs on Slack.

Step 2: Create an SSH key

Next, create an SSH key for your GitHub account. Note that if you're using WSL, be sure to follow the Linux instructions to create your SSH key.

Step 3: Clone the repository

In your terminal, open your home directory, then clone the Braze Docs repository.

cd ~
git clone git@github.com:braze-inc/braze-docs.git

Step 4: Install Ruby

To generate a local site preview, you'll need Ruby version 3.3.0 installed. In the terminal, open braze-docs and check for Ruby version 3.3.0.

cd ~/braze-docs
ruby --version

If this version isn't installed, use a supported version manager to install Ruby version 3.3.0. For example, using rbenv:

rbenv install 3.3.0

Step 5: Install dependencies

If you have multiple versions of Node.js installed, use asdf for version management.

brew install asdf

Next, install the dependencies for Braze Docs. These dependencies are small programs that generate your local Braze Docs site.

  • Make sure you have Bundler 2 or higher.
  • To verify your current Bundler version, run: 
    bundle --version
  • If needed, to upgrade to the latest Bundler version, run: 
    gem install bundler
bundle install && asdf install

Step 6: Start your local server

To verify your installation and start your local docs server on localhost http://127.0.0.1:4000, run:

# for 'en' language:
rake

# for other languages:
rake es
rake fr
rake ja
rake ko
rake pt_br

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

Next steps

If you're new to Git or docs-as-code, start with our tutorial: Your first contribution. Otherwise, check out one of the following.