Running the site locally makes testing and previewing large changes much easier. There are several things you need to do get this working. Fortunately, you only need to do this once.
Using the terminal and command line
On macOS, you can use the Terminal app to access your system's command line. (You can also access the terminal via VS Code.) The command line is an alternative to the graphical user interface.
Here are some basic terminal commands that might be useful:
- pwd (print working directory): Use this to see your directory path.
- ls (list): Shows the files in your current directory.
- cd YOUR_DIRECTORY_PATH (change directory): Moves to another directory.
- cd ..: Move one directory up in your path.
0. Enable VS Code in your terminal
It's handy to be able to open files from your terminal directly in VS Code. You may only use this a couple of times, but it's much nicer than trying to edit files in the terminal itself.
- Open Visual Studio Code.
- Press command + shift + p to open the command palette, then type "install code", and then click Shell command: Install 'code' command in PATH.
- In your terminal, type
code
YOUR_FILENAME` to open that file in VS Code.
1. Use GitHub Desktop to set up your local repository
GitHub Desktop is a graphical tool for managing your branches, commits, and PRs. It's probably the most straightforward way to work with Git and GitHub.
- Install GitHub Desktop.
- Sign in to GitHub Desktop via your GitHub account.
- On Macs, click on GitHub Desktop in the top left corner of your screen and select Preferences. Select the blue Sign In button and follow the prompts in the browser window.
- Navigate to the Docs Site repository.
- Click the green Code button and select Open with GitHub Desktop.
- Choose the location where you want the repo. The default location for this folder is
~/Documents/github
. - Clone the entire repository to your local machine.
2. Enable Full Disk Access
By default, it seems that macOS prevents the terminal from access to certain system folders, like Documents
. Change this setting to make it easier to navigate in your file system via the terminal.
- Open System Preferences.
- Click Security & Privacy.
- In the left pane scroll down until you find Full Disk Access and then select it.
- Click the lock in the bottom left corner and then enter the password you use to log in to your computer.
- In the list of apps, check the box next to Terminal (or whatever your default terminal application is).
- Click the lock to lock it.
3. Install Homebrew
Homebrew is command line tool for installing other applications. It's also an easy way to keep command line software updated.
- Open your terminal.
- Copy and paste this command to your terminal:
$/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
4. Install npm
npm stands for Node package manager. You use this to install nvm, which stands for Node version manager.
- In your terminal, type
brew install npm
.
5. Install nvm
Node version manager, or nvm, is what you use to manage the version of Node installed on your computer.
- In your terminal, type
npm i -g nvm
.
6. Add nvm to your shell profile
In order to run the commands you need for your local build, you need to add the path to nvm to your shell profile.
On macOS, your shell is what interprets what you enter on the command line. The default macOS shell is Zsh. You need to tell your shell the directory where nvm is on your machine, so you can run these commands from anywhere.
You do this by adding some text to your .zshrc
file, which is a config file for your shell.
- In your terminal, type
code ~/.zshrc
to open this file in VS Code. - In the .zshrc file, copy and paste this text:
$export NVM_DIR="$HOME/.nvm"$[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm$[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
- Save the file.
7. Install Node
Once you've installed nvm, you can install the correct version of Node. Node, or Node.js, is the JavaScript engine that powers our Gatsby site and its dependencies.
- Type
nvm use 16
to install Node version 16.
8. Install Yarn
Yarn is another package manager used to compile all of the files in the docs-website repo to build the site locally. You use npm to install Yarn.
- In your terminal, type
npm i -g yarn
.
Build the local site
Once you've installed all of these things in your terminal, you can run the site locally on your machine.
- In your terminal, type
pwd
to make sure you're in the docs-website repository directory. - Type
yarn
to make sure all your Gatsby dependencies are up to date. - Type
yarn start
to build the site locally. - When the process finishes, in your web browser, go to
http://localhost:8000
.
When you run yarn start
, your terminal outputs many lines of text. If your local build fails, the terminal output often provides a clue to what's gone wrong.