Explanation⌗

I wrote an extremely detailed article about contributing to the Resource Center for IBlieve. The assumption was the reader would have no prior knowledge about any of the tools I presented. Therefore, I explained each and every step you need to go thorough - from installation, setting up the environment, to the actual contribution and all things that follow. I turned out almost to be almost 6000 words and 60 pages! I needed to cut it down, but I didn’t want to simply delete it.

That’s why I’m moving a large part of the main article to my personal blog so that if you do not have required knowledge, you can quickly catch up and set up the work environment on your machine.

Hugo installation⌗

To install Hugo, you need to go to the installation page of your operating system – either Windows or macOS (I assume no reader uses Linux, but there’s a page for that as well.) There, you can find several methods for installing Hugo. I’ll explain two methods (one for each operating system) I find the simplest. (One more thing: all methods are different, but what they have in common is that they are all based on Command Line Interface (CLI). Normally, you use Graphical User Interface (GUI) and access functionalities by using mouse and graphical elements. In CLI, you use commands to do the same job instead of mouse and you have computer terminals instead of graphical elements. Different operating systems have different terminals and commands, though sometimes they’re similar. I hope this clarification was helpful. Now we can proceed)

Windows⌗

You need to open Windows PowerShell (Windows’ terminal). You can do this by typing “PowerShell” in the search box (Fig.1). Make sure you open “Windows PowerShell” without “ISE” at the end.

This should pop up a console that looks like this:

Now, we need to install a packet manager to install Hugo itself. (Reasons why we need this step are not important here, but feel free to look them up!) We will be using scoop as a packet manager, but chocolatey will do as well. With the PowerShell open, we need to type two command:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

After executing this command, agree to the execution policy by typing “y” (Fig.3)

irm get.scoop.sh | iex

And the installation of scoop should begin (Fig.4).

Finally, we can install Hugo by executing the following command: scoop install hugo-extended and Hugo should start installing (Fig.5).

scoop --help

macOS⌗

To install Hugo on macOS, follow instructions from the video below:

In contrast to the Windows’ “scoop install hugo”, the “brew install hugo” command on mac installs the extended version of Hugo by default.

Hugo commands⌗

You can now execute the command “hugo –?” to get a glimpse of the Hugo functionality or go straight to the documentation to get a full picture. You may not need all of it, but it’s worth checking out as you go.  

Git⌗

Git is a version-control tool, meaning you can track you progress: see what changes you made, come back to a point in history, see what others did, store project in a cloud and many more. We’ll need git to make changes to the Resource Center and host them online. To do so, we need to install git and set up a GitHub account (more on GitHub later). (Although you’ll learn the minimum of what you need to contribute to the Resource Center, I recommend watching this video as it is a good introduction to git and GitHub that’ll give you a broader perspective.)

Git installation⌗

Installing git looks very similar on both Windows and macOS.

Windows⌗

To install git on Windows you need to open either PowerShell again or Command Prompt a.k.a cmd (another Windows’ terminal). (For our purpose, it doesn’t matter which one you use, but you can read about differences between them.) After opening of the above, run:

scoop install git

And voila! You’ve just installed git (Fig.6a-c).

macOS⌗

Before installing git on macOS by yourself, make sure it is not already installed on device. Many Apple devices come with preinstalled git. To check that, open the terminal and execute:

git --version

If you get something like this “git version 2.7.0 (Apple Git-66)”, you don’t have to do anything. If you receive a “command git not found”, it means you need to install git manually. I recommend the video below:

GitHub⌗

GitHub is an online service for hosting git repositories, providing back-up of your work, enabling collaboration in open source projects (such as the Resource Center) and much more. There are other similar services such as GitLab, but the idea is the same.

To collaborate on the Resource Center, you need a GitHub account so let’s see how you can set it up.

GitHub account⌗

To kick off, go to the GitHub web and click “Sign up” (Fig.7).

A nice invitation should appear along with a first blank to fill (Fig.8).

Now, provide all data and verify your account like so (remember to write your data, not from the example):

Go to your email where verification code was sent (Fig. 11). It will be different than the one below!

You need to copy it and paste it here:

This will bring you to the personalization page (Fig.13). You may complete it you if you want or go straight to your newly-created dashboard by clicking “Skip personalization.”

And done! You’ve just set up your GitHub account!. We’ll return to it shortly after installing Visual Code Studio.

Visual Code Studio⌗

Visual Code Studio (VSCode) is a popular code editor managed by Microsoft. Although we don’t have to use this particular code editor and even a notepad will do, it is recommended to use a good code editor as it simplifies writing projects. Besides, since VSC is popular, there’re plenty of materials about this tool across the web for you to learn from.

VSCode installation⌗

To get VSCode, go to the download page of VSCode website and choose your operating system (Fig.15).

The installation should begin and you should be directed to the tutorial page (Fig.8).

After this step, things look a little bit different for mac and Windows users. For macOS, the following video shows everything you need in the installation part:

For Windows users, follows the steps from below.

Go to the “Downloads” folder and look for “VSCodeUserSetup”. Click it and another windows should pop up with the terms of use. Agree to it and click “Next” (Fig.17).

Now, you’ll have to click “Next” twice. Do not change the default settings (unless you’re completely sure what you’re doing) because this may cause some problems later. Like so:

Next, click “Install” (Fig.20). This should create a usable shortcut on your computer after a few seconds/minutes, depending on your internet connection.

Lastly, click “Finish” and wait for the VSCode to open (Fig.21a-b).

Getting started with the project⌗

Having all necessary software installed, we can now combine all the tools together!

Forking the repository⌗

To edit the Resource Center, we need to fork the original repository, that is, we need to make a copy of the original repository with the Resource Center on our GitHub.

Go to the following link: https://github.com/bprzybylski/IB-CS-GeS where the original repository is hosted. You should see a “Fork” button near a “Code” button (Fig.22). Make sure you’re logged in!

After clicking the Fork button a “Create a new fork” page should appear where you can edit the name and description of the repository (Fig.23.I-II). When you’re done with editing, click “Create fork” to finalize forking the repository (Fig.23.II).

Within a few moments, the repository should be forked (Fig.24).

However, it would be difficult (though possible) to edit the Resource Center in the browser. Therefore, we need to create a local version of the repository (copy all the files into our device).  

Local version⌗

First off, you need to create a folder where your project will be stored. Even though it is not required, it is a matter of good practice to do so. You just need to open a terminal and type the following command:

mkdir Projects

You can replace “Projects” with whatever you like. Now we need to navigate to the folder we created. For that, we need a “cd” command. When you use:

cd [relative_path]

you go inside the folder you typed (is one exists – relative_path is an actual path to a folder). When you type:

cd ..

you return to the folder one level higher in the hierarchy. So if you created a folder “Projects”, you type

cd Projects

Now, we need to clone our repository (make copy on our device). Without closing terminal (PowerShell, cmd, or Terminal), go back to your online repository. Click the “Code” button (Fig.25.I), choose the “HTTPS” option (Fig.25.II) and copy the link from there (Fig.25.III).

Your link will be different, containing your user name. After copying, open the terminal once again (make sure you’re in the Projects folder) and write “git clone” (Fig.26.I) followed by the link we copied (Fig.26.II).

Run the command and the cloning of the repository should be initiated (Fig.27).

Setting git⌗

We’re not ready yet as we have to more things to do.

Adding theme submodule⌗

First, we need to update our theme because this folder is now empty (theme is appended as a git submodule which is not initiated when the main repository is cloned) (Fig.28).  

Fortunately, all we need to do is run the command:

git submodule init

followed by:

git submodule update

as depicted on Figure 29.

And if we return to the theme/hugo-book folder, we should see the files of the theme (Fig.30).

Adding our data to git⌗

Second, we need to tell git who we are. Fortunately, it only requires two commands:

git config --global user.email you@example.com

and

git config --global user.name "Your Name"

You don’t have to use the “–global” flag. It just sets the data you provides as a default configuration for all your git projects. So we’re going to use this flag (Fig.31).

Your environment is set up and ready to go!