Authoring workflow

Collaborating is a resposibility, therefore please make sure you get acquainted with Git and GitHub.

These are the normal steps involved;

Create a GitHub account
You need to create your own github account as this is where you will be saving your version of the book.
Fork the repository
Basically you will be copying the book to your repository by “forking it”.
Download your fork locally
Now you can download the your own copy of book, “your fork”, to your computer using Git, which by now you should be very familiar with.
Do your changes
Create new pages alter others and explore “what if” scenarios in the safety that this is your own copy of the book.
Push your changes
Once you are happy, you will upload or “push” those changes to your own github fork.
Create a pull request
Now is time to notify me that you want me to merge things, this is called a “pull request” and I will go over every single change you want me to merge, of course, some may need extra work and this will go back and forth for a bit until I am satisfied and approve it.
Your branch will be merged with mine and will go live for everyone to see.

Create a GitHub account

You need to create a GitHub acocunt if you don’t have one already before proceeding, this is how.

If you don’t know GitHub I will strongly suggest you check the various GitHub Official Training Guides or other YouTube tutorials and online git books and onlinne gihub books which surely will help you, not only to collaborate but on your own projects.

How to fork a repository

The best thing to do is to go to the (GitHub help pages]( on how to fork a repository and the cloning proces.

> git clone<YOUR-GITHUB-USERNAME>/houdini-guides

Now you will have a clone of your own version of the houdini-guides in your local drive, you can do whatever you want here without fear or breaking anything at all.

Create a new post

Create new posts using the correct structure is not hard, just have a look at the book structure that has been downloaded and you will see quite clearly how things are setup.

For example, to create a chapter on the animation part-2

> hugo new post book/part-2/animation/keyframing/

Will create a chapter under the animation block and the is the document you need to add your text, images and what not.

Please check the markdown guid and the style guide to find more about it.


I am not a native speaker so I need all help I can get, for this reason I highly recommend using Grammarly to correct or even write the articles.

Dealing with images

The strategy is to keep your original images including photoshop files and the likes under the article folder like this..

..and produce lightweight jpg versions that we can use for the web pages, this are the ones you should link to.

JPEG Compression

Make sure you use MozJPEG codec to compress these images to the maximum. I normally use Image Optim during my authoring process to make sure I have really fast page loading.

Dealing with diagrams

At the moment this has not been put in place but very soon I will be installing a markdown style diagraming system so we can produce text based diagramas that render on the fly rather than dealing with heavy images, staty tuned.

Publishing your changes

Once you are done with the content, double checked your grammar, typos and what not (I recommend using Grammarly for this), you can publish it to your GitHub repository like this

> git add --all
> git commit -m "New keyframing chapter under animation"
> git push

Doing a Pull Request

Now go to the original GitHub Houdinig Guides repository and click on Pull request;

Pull Request Menu

Merging with main branch

Once the pull request is approved I will proceed to merge it and will become live immediatly.

Image of the pull merge process

Deleting your fork

Once I have merged your brand you may want to delete your fork and start the process again with a new fork. Remember that there may be lots of people collaborating and your branch will become obsolete very rapidly.

Image of the branch history / graph