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.
$ lsfolder-on-desktopanother-folderdocs$ 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-namegit 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
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:
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:
Create a new branch on your forked repo.
Find in the folders where the new content will be placed.
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:
For Node.js versions 16.10 and lower, you can run:
npm i -g corepackcorepack 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 nodenode –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
yarn. Once installed, the following commands below can be used. If using
yarn, you can switch
npm to say
npm installnpm run format:verifynpm 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.
Connect with other contributors and get answers to your questions in Forums.