Accept cookies for analytics, social media, and advertising, or learn more and adjust your preferences. These cookies are on by default for visitors outside the UK and EEA. Privacy Notice.
The NGINX Wiki is automatically generated from reStructuredText files using Sphinx Documentation Generator. The source files are stored in GitHub and are open to contributions via pull requests. This document will help guide you through this process.
Whilst viewing wiki you will find “Edit on GitHub” links in the sidebar on every page. Using this you can edit page content and submitting your edits will generate a pull request. This is a relatively simple way to make quick edits.
These instructions are for Linux and Mac users, and assume you have a GitHub account and the git
command-line tool is installed.
You also need python-sphinx installed; some Linux distributions have this in their repositories, while for others you can install it using pip
:
$ sudo pip install -r requirements.txt
If you use GitHub’s two-factor authentication (highly recommended), you can use an access token instead of a password when accessing GitHub with the instructions outlined in this document. This can be obtained from your application settings page.
Alternatively, you can use SSH to access GitHub. Simply go to your SSH keys page, add your key, and change the URLs in this document from https://github.com/<user>/nginx-wiki.git
to git@github.com:<user>/nginx-wiki.git
.
You need to create a fork of the source so that you have a working area for it. To do this go to the NGINX Wiki GitHub page, sign in, and click the Fork button near the top. Once you have forked you can get a local copy of this fork to work on. To do this, run the following command in your console (where <user> is your username):
$ git clone https://github.com/<user>/nginx-wiki.git
You then need to associate your local clone with the upstream repository:
$ cd nginx-wiki
$ git remote add upstream https://github.com/nginxinc/nginx-wiki.git
Every new batch of additions/edits you want to merge into the Wiki needs its own branch. Before creating a new branch, first make sure your local copy is up to date:
$ git checkout master
$ git pull --ff-only upstream master
$ git push
You can then create a new branch based on the master (replacing <branch-name> with the name you choose for the branch):
$ git checkout -b <branch-name>
Hack away on the changes you wish to make. See Writing Documentation for more information.
Once your edits are ready to test, run these commands to check that they build correctly:
$ make dirhtml
$ make linkcheck
If either command generates an error, your edits probably need fixing.
If you’ve recently run make linkcheck
and many permanent redirects were found, you can automatically replace them all by running:
$ make linkfix
This script is just a quick hack for the lazy, so make sure to check that it didn’t break anything syntactically before you commit.
One way to preview the output is to use NGINX. The build system can already setup NGINX for you if you have it installed:
$ make serve
Or if you have NGINX in a non-standard path (for example /opt/nginx/
) you can point to the path of the NGINX binary with:
$ NGINX_PATH=/opt/nginx/sbin make serve
You can then use your web browser to go to http://localhost:8080/
and view the result.
When you are done, CTRL-C will exit NGINX.
When you are ready to submit your changes, you need to commit them in your cloned repository and then push them up to GitHub.
If you have never pushed code up to GitHub before, run these commands to register with git
:
$ git config --global user.name "Real Name"
$ git config --global user.email "[email protected]"
Use git add
to add any new files to the respository, and then commit:
$ git commit -a
Your default text editor pops up. Enter a commit message above the comments. The first (subject) line should describe the purpose of the commit in no more than 50 characters. The second line should be blank. The third line onwards can contain details, with no more than 72 characters per line.
If your commit fixes an issue, the first line might be something like this example for issue #45:
Fixes nginxinc/nginx-wiki#45
Once all your commits are done, you might need to do a quick rebase to make sure your changes will merge correctly into the master branch:
$ git fetch upstream
$ git rebase -i upstream/master
Your editor should pop up again with a commit-style message that has pick as the first word. Save the message and the rebase will complete. If the rebase tells you there is a conflict, you will need to locate the problem using git diff
, fix it, and run these commands:
$ git add <filename>
$ git rebase --continue
If things look like they are going wrong, you can undo the rebase using the following command and then get in touch with the NGINX community team for help:
$ git rebase --abort
You should now be ready to push up to GitHub:
$ git push --set-upstream origin <branch-name>
When you go to your repository on GitHub’s website, you will see an option to file a Pull Request. Use this to submit a pull request upstream for your branch. You are welcome to make multiple commits in a branch before submitting the pull request.