-
Notifications
You must be signed in to change notification settings - Fork 4
Setup
In this article you'll learn everything you need to run the website on your local computer. The audience of this article are content maintainers of the website. However, developers that are unfamiliar with the setup of the website may find this article useful too.
This section is intentionally simplified. It provides additional context at various stages. If you're just interested in creating content such as a news item then this section provides all the tooling you need to get started.
If you have not done so yet then sign up for an account for GitHub. You'll need this later in the process.
This section is specifically for Windows users, however similar tooling is necessary for Linux and MacOS.
The following tooling is necessary to interact with GitHub:
- Git: Git is a version control system.
- GitHub Desktop: GitHub Desktop provides a user-friendly interface to interact with GitHub through Git.
- Visual Studio Code: Visual Studio Code or VSC for short is a code editor.
The following tooling is necessary to build the website:
- ImageMagick: ImageMagick is a free, open-source software suite, used for editing and manipulating digital images. It has an extensive command line interface. It is used by one of the plugins of the website to automatically convert images to browser-friendly formats.
- Ruby: Ruby is the programming language that Jekyll is built in. We need it in order to run Jekyll.
-
- Jekyll: Jekyll is a static site generator. It is used to generate the website based on our content and configuration.
-
- Bundler: Bundler is a package manager for Ruby. A package manager is in some fashion similar to the map or mod vault of FAForever. It helps us with managing dependencies.
Ruby is required to install Jekyll and bundler. The link to Jekyll provides additional instructions on how to install Jekyll via Ruby. Open a command prompt. Confirm that Ruby is installed with:
ruby -v
gem -v
If it returns you a version number then you are good to proceed. You can install Jekyll and Bundler by typing the following into a command prompt:
gem install jekyll bundler
Close all command prompts, then open a new command prompt. This refreshes the environment variables for the command prompt. To verify that the installations all worked you can run the following prompts:
git -v
bundler -v
jekyll -v
If they all respond with a version number then you're good to proceed.
Github Desktop You can follow the installation instructions here to install and setup Github Desktop.
ImageMagick You can download the AppImage for ImageMagick here
You can use the official installation instructions of Jekyll to have Ruby, Bundler and Jekyll working.
In this section you'll create a personal instance of the website via forking. Forking means that you are creation your own copy of a repository. A repository is a code base. Then you'll clone your copy of the repository with GitHub Desktop to your computer. Cloning a repository means that you are downloading the repository to your disk. Once the files are on your computer you're good to proceed to launch a local instance of the website. This allows you to preview your changes, such as a new news item.
Navigate to the repository on GitHub. Fork the repository by clicking the fork button. It is to the right of the title of the repository. Throughout the forking process the default properties should suffice.
By forking the repository we create a playing ground where we can do anything with no consequences to the actual repository. After the forking process is complete your browser tab should end up in the forked repository. You can confirm this by looking at the title of the repository. Just below the title it should state it is forked, with a reference to the original repository.
Open GitHub Desktop that you previously installed. In the menu bar navigate to File -> Options. In the new dialog open the Accounts tab. There you can login to your GitHub account.
Once you are logged in we are ready to clone your fork of the repository. By cloning it you download the files of the repository to your computer.
In menu bar of GitHub Desktop navigate to File -> Clone repository. In the new dialog it should already show the repository you just forked in the list with the label Your repositories. If you can not see the repository here then make sure that you have logged into the GitHub account that you previously forked the repository with. Choose a location to store the repository and its content. Then proceed to click on Clone.
Once the process is complete the interface of GitHub Desktop changes. It may start with a new dialog that asks you what your intentions are. If you're interested in maintaining the content of the news website then choose To contribute to the parent project. This hides a lot of technical details and simplifies the process of contributing for you.
Just below the menu bar of GitHub Desktop you should see the current repository. That current repository should be set to your fork of the news website. By right-clicking it a small submenu opens up. Click on 'Show in Explorer'. This will open the folder that the repository resides in.
In the Windows Explorer open the src folder. You should find the following files in that folder:
-
_setup-install.sh: Runsbundle installwith the current folder as the working directory. -
_setup-serve.sh: Runsbundle exec jekyll servewith the current folder as the working directory.
These will help you with installing the packages and serving the website on your machine. You can (and should!) inspect the bash files in Notepad. Run the installation script first. Then run the serve script. The serve script may take a while to run initially. This is because it has to build the image cache.
Assuming that no errors occurred, then the serve script should end with something similar to:
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.
If you open your browser and navigate to the address you'll see the news website. This instance is running locally on your machine. You're ready now to proceed. If you make changes to the source files, by for example creating a new post in the _posts folder, the website will rebuild and the changes will be visible after refreshing the page in your browser.
As a developer you won't need much more configuration then what is mentioned in the section for content maintainers. The use of of a package.json implies the need of Node, but that is only used during the Continuous Integration (CI) pipeline. Beyond a good IDE to work with Liquid there's no additional suggestions.
What about it? You get what you paid for mate.