Setup guide

• Prerequisites
  • SSH keys
  • Homebrew
  • npm
  • Atlas token
  • Git
  • Vale
  • Visual Studio Code
• Instructions
  • Clone the repository
  • Build a preview

This guide takes you through the steps to set up the developer documentation hub on your local machine.

Note: This guide targets macOS users, but the same steps apply to all platforms.

Prerequisites

Before you begin, you need to have the following dependencies installed on your machine.

SSH keys

If you interact directly with the dev-docs repository as a member of the Adjust organization, you need to set up an SSH key with SSO signin. To do this:

1. Create a new SSH key. You can do this using 1Password or by generating a key on your machine.
2. Add the SSH key to your GitHub account.
3. Set up your SSH key for SAML single sign-on.

Once you've got your SSH key set up, you will be able to interact with the repository directly.

Homebrew

Homebrew is a package manager for macOS that enables users to install various tools with a simple command line interface.

1. Open the terminal app on your Mac
2. Paste the following command and hit return:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the instructions in the terminal to complete the installation

npm

npm is a command line utility for managing Javascript dependencies. You need to install this to install and manage the software that powers the developer hub.

With Homebrew installed:

1. Open the terminal app on your mac

2. Enter the following command and hit return:

   brew install npm

3. Follow any on-screen prompts

Atlas token

The developer hub makes use of Atlas components to build the site and make content more visually appealing. To download Atlas as a dependency, you need the Atlas team to grant you access to the Atlas GitHub repository. Once your GitHub user is authorized to view the Atlas repository.

1. Create a classic Personal Access Token (PAT) by following GitHub’s instructions. Ensure that you give the token at least the read:packages scope

2. Copy your PAT and open the terminal app on your mac

3. Create a .npmrc file in your user directory.

   touch ~/.npmrc

4. Using an editor of your choice, edit this file to enter the following information:

   //npm.pkg.github.com/:_authToken={your_PAT}
   @adjust:registry=https://npm.pkg.github.com/
   

   Important: Replace {your_PAT} with the Personal Access Token you copied in step 2

5. Save the file

Once you’ve added this information to your root .npmrc file, any requests made to the GitHub package repository will be authenticated using your PAT. This gives you access to the Atlas repository.

Git

Git is a distributed source control manager that powers the workflows used in the developer hub.

With Homebrew installed:

1. Open the terminal app on your mac

2. Enter the following command and hit return:

   brew install git

3. Follow any on-screen prompts

To handle image files, the dev hub is configured to use git-lfs. You can install git-lfs with Homebrew.

1. Open the terminal app on your mac

2. Enter the following command and hit return:

   brew install git-lfs

3. Follow any on-screen prompts

Vale

Vale is a prose linter which can detect and highlight issues with prosaic text based on rulesets. We use this to check our writing against the Microsoft Style Guide. Vale will highlight any language which doesn’t conform to the style guide’s rules when you save a document.

With Homebrew installed:

1. Open the terminal app on your mac

2. Enter the following command and hit return:

   brew install vale

3. Follow any on-screen prompts

Visual Studio Code

Visual Studio Code is a code editor with excellent support for the developer hub’s content and workflows. Head to https://code.visualstudio.com/ and download it from the web page.

Instructions

Clone the repository

Once you’ve completed the prerequisite steps, you can clone the developer hub repository to your local machine to work on the documentation.

1. Open the terminal app on your mac

2. Navigate to the directory where you want to keep the repository. In this example, I create a new directory (mkdir) named git and then navigate to that new directory (cd)

   mkdir git
   cd git

3. Use git to clone (copy) the repository from GitHub to your local machine

   git clone [email protected]:adjust/dev-docs.git // SSH cloning for Adjust team members
   git clone https://github.com/adjust/dev-docs.git // HTTPS cloning for external contributors

4. You now have a copy of the repository located at ~/git/dev-docs. You can open this folder in Visual Studio Code to browse the source code.

Build a preview

Once you’ve cloned the repository, you can build a local preview of the developer hub using npm.

1. Open the terminal app on your mac

2. Navigate (cd) to the project directory. In this example, the repository was cloned to ~/git/dev-docs

   cd ~/git/dev-docs

3. Install all npm dependencies. This may take a while as packages resolve.

   npm i

4. Once the dependencies are installed, run the following command to start a local preview:

   npm run dev

With the preview running, you can view the site at http://localhost:4321. To stop the preview, return to the terminal app and press ctrl+c.