Sign Up For Our Newsletter
Copyright 2020 The Blockchain Institute. All Rights Reserved
This guide provides the basic instructions to begin contributing to the site using local tools. We will cover how to download the repo using the Github Desktop client, how to use VSCode to run the site locally, and how to checkout a new Git branch and submit changes for review.
Github’s desktop application supports a range of features including cloning, editing, and pushing changes to Github repositories. Install it now as we will need it in subsequent steps.
Click here to download and install Github Desktop
Visual Studio Code is a premier software editing tool which integrates quite well with Github. It also supports a number of features like an integrated terminal, which will make editing the website files much easier.
Click here to download VSCode.
Ruby is a software language that supports a range of CMS tools including Jekyll, which Github Pages will be using to serve our website.
Click here for instructions on downloading Jekyll and Ruby for your operating system
The Weteachblockchain.org website runs on the Github Pages system, which means that all you need to do to make changes is commit a new branch to the Github repo. We’ll step through this process in this section.
In order to start working with the repository locally, you’ll first need to copy the files locally by using the clone feature. To get started, open the root of the repository in your web browser.
Click here to open the repository in your browser
Then, follow these instructions to clone the repo
Github organizes code into branches within a repository. A branch is essentially a group of sequential changes. Once a branch has been approved, it can be merged back into the master branch of the repo, and your changes will be made live on the WeTeachBlockchain website!
Follow these instructions to create a new branch with the Github Desktop Client
Now that you have your own branch, you can make changes to any of the files contained in it, and then commit the changes. Committing changes will add the newly edited files to your branch, which will allow you to push them to Github.
Watch this tutorial for more information about how to commit changes using Github Pages
Once you have finished making changes, you will need to push your newly created branch from your local machine to the cloud hosted Github repository.
Follow this section of the tutorial to push changes to the remote repository
Once your changes are complete, and you have successfully pushed them to the cloud repository, then you can request that a member of the Blockchain Institute staff review them. In order to request a review, you can submit a Pull Request.
More information on submitting pull requests here
VSCode is a very useful tool for working with software and provides lots of great features out of the box including github management and CLI access.
Once you have downloaded the project files using Github, you can open the main folder in VSCode to begin working with the files. If you cloned the repository as weteachblockchain.org (default) then you should be able to simply right click the folder and select ‘Open with VSCode’. If this is not available, open VSCode and select File > Open Folder from the top dropdown menus.
Assuming that you successfully opened the folder, and have installed Jekyll and Ruby properly, you may now run the server locally. This will start a local web server, and allow you to test changes before submitting a pull request.
Note: Not all users will need to test changes using a local server. If you are just making simple changes, or editing text or typos, this may not be necessary for you.
With VSCode open, type [Command]+[~] to open the terminal, or use the dropdown menus at the top of the screen (Terminal > New Terminal). This should open a command line terminal which will allow you to run scripts.
Once the CLI is open, enter the following command to install dependancies:
bundle install
bundle exec jekyll serve
Open a browser and navigate to localhost:4000 to view the site.
As you make changes, you will see the server reload in the terminal. Be sure to save the files in order to trigger the automatic reload.
In order to stop the server, you’ll need to cancel the serve command. This can be done simply by clicking on the terminal window and typing [Ctrl] + [C]. Some operating systems may requite [Ctrl] + [Shift] + [C], so try both to be sure!
If you’d prefer not to use Github Desktop, or are unable to do so, you can also use the VSCode Source Control Management (SCM) pages to commit changes and create new branches.
For a tutorial on using VSCode SCM, Click Here
If you ran into problems anywhere in this tutorial, please email us at [email protected] and we will be happy to assist you!