How do I contribute to DOCS

dev
1

Hi, I was wondering how I can contribute to the documentation. As a new user, I felt there was this one key piece of information that could tie the loose ends on user defined Params for users who are comfortable with HTML+CSS+JS, but for whom leaving the site to read the Go templates language documentation in detail would be overkill. I see it keeps coming up at discuss.hugo.io.

I added a couple of paragraphs and sample code to the Page Params section of variables.md.

Anyway, as much as I’ve used git and GitHub for myself, I had never submitted a pull request before. I cloned the hugo repository, expanded content/variables.md, created a branch called rindolphus and then tried to push it, and send a pull request. Both failed with a “You may not have permission to access hugo. Check Preferences to make sure you’re still logged in.” message.

And the README says to go ask here, so here I am :stuck_out_tongue: Admins, any thoughts?

2

Hello @rindolphus,

first off all thanks for your willingness to contribute to Hugo. The docs are indeed are part that could be made a bit more user-friendly as we’ve heard in other discussions. Especially new users might have a better sense for things that could be improved or aren’t obvious in the current state of the documentation.

However, let’s tackle your problems with git/github.

The message You may not have permission to access hugo. Check Preferences to make sure you’re still logged in. occurs because you don’t have direct write access to the Hugo repository on Github.

The following instruction should help you to create a pull request on Github. Depending on your experience with git/github just ask if you stuck somewhere.

  1. First, please log yourself in to Github. Now move to the Hugo repository. At the top right you should find a button called fork.

  2. Next, click this button. Now you should have create a new repository for your account. It’s available at github.com/rindolphus/hugo. A fork is an independent copy of Hugo itself. A fork is needed to create a pull request on Github.

  3. Now open a command line and move to the local git repository in which you made the changes in the documentation.

  4. Enter git remote -v. Now you should see all remote repositories (the repos on Github) that your clone knows. Since you cloned the orignal Hugo repository you only should see this remote repository listed like below:

    origin	https://github.com/spf13/hugo (fetch)
origin	https://github.com/spf13/hugo (push)

  5. We need to add your fork as remote repository. Since the fork is your own repository you will have write access. Let’s add the your fork as remote repository to git. Enter the following to the command line.:

     git remote rename origin upstream
 git remote add origin https://github.com/rindolphus/hugo.git

    Now, let’s check if everything went well. You should see four entries:

    origin	https://github.com/rindolphus/hugo.git (fetch)
origin	https://github.com/rindolphus/hugo.git (push)
upstream  git@github.com:spf13/hugo (fetch)
upstream  git@github.com:spf13/hugo (push)

    If so, we can move on.

  6. Now checkout to the branch where your changes were made. In the time between you additions and now other users could have made some changes too. Let us pull these changes before pushing them to your own Hugo fork (origin).

     git pull --rebase upstream master

  7. Now we should be ready to push the additions. If you used an already existing branch like master you can do

     git push

    If you created a seperate branch we need to create a branch in your fork (origin):

     git push --set-upstream origin <NAME-OF-YOUR-CUSTOM-BRANCH>

    Now you should see your changes in Github in the branch we created a few second ago.

  8. Now, we are ready to create a pull request. In your repositoy you should see a small panel asking you to create a pull request. Click on the green button and move on.

  9. You should be redirected to a new site. You commit should have a short and descriptive title and commit message. Edit those fields if neccessary. We can update them later if you’re unsure.

  10. Click on Create pull request and you’re done.

Hopefully, we see us on Github again. If you have problems at any stage with the instruction above please leave a comment. It could also be possible that I forgot a detail.

We appreciate every contribution that improves this project.

3

Thanks a lot @digitalcraftsman for taking the time to post such a detailed guide. It worked great. Here’s the pull request (I’m renatovargas on GitHub):

It’s just a small addition, but I hope it’s useful.

4

Great. I wrote you back at Github.