Home » Documentation guide »

Learn Git by editing the Write the Docs website

Identify the page you want to edit

  1. Find an existing issue, or a page you want to improve.
  2. In the repo UI, find the file that corresponds to the page. For example: https://www.writethedocs.org/documentarians/ is produced by /docs/documentarians.rst. (You’ll need this filename later for making changes on your local copy.)
  3. This is a ReStructuredText (.rst) file, so you may want to review the RST documentation. Other common markup formats are Markdown (.md) and AsciiDoc (.adoc).

Prerequisites

  1. Create a GitHub account.
  2. Download and install Git.
  3. Open a terminal window and follow the instructions to associate your GitHub username with your local Git installation.
    1. In macOS: Open the Terminal app.
    2. In Windows: From the Start Menu, open Git Bash.

Start using Git and modify the source file of a page

  1. Visit the Write the Docs www project.

  2. Click the Fork button in the upper-right corner to create a copy of the project in your GitHub account. The new page for the forked project opens.

  3. Click the Clone or download button and copy the https URL from the project page.

  4. Open a terminal window so that you can run git commands.

    1. In macOS: Open the Terminal app.
    2. In Windows: From the Start Menu, open Git Bash.

  5. Navigate to or create the directory to where you want to clone the repository.

  6. In your terminal window, type git clone, followed by a space, and then paste the project URL:

    git clone https://github.com/myname/www.git

  1. Press Enter. The command copies files from GitHub to a folder named www on your local machine.

  2. In the terminal window, go to the www directory.

    cd www

  3. Create and switch to a branch. Using the commands below, replace branch-name with a name that briefly describes the changes you’ll make, preferably use dashes between words. For example, important-typo-fix.

    1. Create a branch with:

      git branch branch-name

      Switch to the branch:

      git checkout branch-name

    2. Alternatively, use one command to perform both steps at once:

      git checkout -b branch-name

  4. Open the www folder on your computer.

  5. Open the file you wish to edit using a text editor like Sublime Text or Visual Studio Code, then save the file.

  6. In your terminal window, type:

    git status

    This will show you all the files that you have updated.

  7. If your changes look accurate, enter the following in your terminal window:

git add -A

This will add any new and changed files to your local project.

  1. To save your changes, enter the following in your terminal window:
git commit -m "Your message"

This will save all of your edited files. Replace Your message with a description of the update you made. Protip: Learn how to write a good commit message.

You can repeat the same process to add multiple commits in your branch.

  1. Send your commit(s) to your GitHub project using git push. Enter the following in your terminal window:
git push -u origin branch-name
  1. Create a GitHub pull request in the Write the Docs www project.