Getting set up on your computer

To get set up on your computer, you’ll need to fork the Docs repo, create a new branch, and create a markdown file containing your entry. The following instructions represent two common workflows. It is also a good way to brush up on Git from the command line.

Create a local copy of the Docs repo

It is important to fork the Codecademy/docs repository. This mitigates any conflicts when merging changes.

The forked Docs repository (on your remote repository) can then be cloned on your local machine from the terminal using the forked repository’s URL which you can find on the GitHub page of the remote repository under the green button labeled “Code”:

Get the URL from your remote repository that you just forked and not the URL from the original repository. You’ll be able to confirm this with your username that should be included in the URL.

From the terminal, run the git clone command using the HTTPS URL:

git clone https://github.com/github_username/docs.git

Before making any new changes, make sure the main branch of the remote repository is up to date with that of the original repository’s main branch (Codecademy/docs:main). You can do this by first going to your forked repository on GitHub, click on the sync “Sync fork” button, and then click “Update branch”:

Within the terminal, change the directory to where the cloned repository lives on your local machine. If your project folder exists in the current directory, you can double-check with the ls(list) command. Then you can navigate into the project by using the cd (change directory) command.

$ ls
folder-on-desktop
another-folder
docs
$ cd docs

To pull down the changes to your local repository, confirm that you’re on the correct branch with the git branch command. If you’re not on the correct branch, you can shift to it using the checkout command and then pull.

git checkout branch-name
git pull

Create a separate branch in the forked repository

Another important point is to never push changes from your forked repository’s main branch. This is to ensure that reviewers and maintainers can test your changes on their own forks. If the changes are pushed from the main branch, they can not do this. Therefore, you must switch to a separate branch before editing files. Create a new feature branch for every new issue you work on with the checkout command:

git checkout -b separate-branch

Create a markdown file for your entry

A markdown file ending with the .md extension needs to be created for every new entry. All content needs to be in markdown. If you’re not familiar with markdown, it is best to check the Markdown topic on Codecademy and take a look in the content folders of other entries as a guide. Generally, the file path for your markdown entry will be included in the issue description. To create a new file, it’s important that you follow the project’s structure within the content folder. Every file must be nested in a corresponding folder of the same name (/folder-name/folder-name.md). Notice that these folder and file names correspond to the URL on Docs. All names should be in lowercase and separated by dashes where applicable. The folder and file that you create should be in lowercase and would follow this general path for topics, concepts, and terms, respectively:

1. docs/content/<topic-name>/<topic-name>.md.
2. docs/content/<topic-name>/concepts/<concept-name>/<concept-name>.md
3. docs/content/<topic-name>/concepts/<concept-name>/terms/<term-name>.md

The exception to the lowercase name would be a term that is written in camelCase. In this situation, the folder and file name would also be in camelCase.

Using the GitHub UI

As an alternative if necessary, the prior steps can be performed from GitHub’s user interface (UI) online. This is outlined below:

1. Create a new branch on your forked repo.

2. Find in the folders where the new content will be placed.

3. Create and name a new file.

Additional set up needed

There are continuous integration (CI) workflows in place to test changes introduced in a PR. These tests can be seen at the bottom of the PR. It is highly recommended to test your changes before submitting a PR. In order to test your changes there are tools that need to be installed first:

For automatic testing, you need node 16.0.0 or newer. While npm comes with Node.js, you will have to install yarn. For Node.js versions 16.10 and higher, you can run this command in your terminal:

corepack enable

For Node.js versions 16.10 and lower, you can run:

npm i -g corepack
corepack enable

To ensure that you have Node.js, npm, and yarn installed, you can run the following commands to check for its location on your computer as well as its version, respectively. For example, to check for node you would run:

which node
node –version

After this is installed, testing will run every time a commit is made. You should see something like this:

To test manually, you will either use npm or yarn. Once installed, the following commands below can be used. If using yarn, you can switch npm to say yarn.

npm install
npm run format:verify
npm run format:all

After the tests are done, remember to push your changes.

Note: nvm is recommended and allows for multiple versions of node. This is useful in cases where certain features are only available in older versions that are not available in the newer versions, or vice versa. Depending on your project, there might be a feature you need or your code might break.is recommended and allows for multiple versions of node. This is useful in cases where certain features are only available in older versions that are not available in the newer versions, or vice versa. Depending on your project, there might be a feature you need or your code might break.