Chapter 2 Basic Setup

2.1 Getting Started

If you want to make simple changes to the website like editing the text on certain pages, you can do this directly through the Github page https://github.com/alabenian/mobilebaydsa without going through the rest of the setup listed here. Just open the markdown file you want to edit on the Github repository site, click the edit icon on the top right, make the changes you want, and finally make a request to commit them.

If you want to make more complex changes to the site, you’ll first need to establish a local branch to work on. I’m writing this guide under the assumption that you’ve never used Github before, in which case I’d recommend working through Github Desktop and Visual Studio Code. After downloading those apps, open Github Desktop, set up a Github account and follow the app’s instructions to clone the repository alabenian/mobilebaydsa into whatever directory you’d like. Then open the folder with Visual Studio Code, and install the following command-line tools in your terminal (either as a standalone “command prompt” window or from the bottom terminal tab in VSCode).

There are three command-line tools in total used to build the site: Jekyll, Tailwind, and Markwhen. Installing Jekyll takes the greatest priority, as it is necessary to build the site to view your changes before publishing. Tailwind is second, because it generates CSS for any Tailwind class you use (and I’d rather not move away from using Tailwind classes primarily across the site). Finally, Markwhen is only used to render and update the timeline used on the Calendar page of the site, and isn’t necessary to install locally at all – this should already be automated with Github actions.

Jekyll (https://jekyllrb.com/) simplifies work on the site by structuring the files by root directory markdown (or HTML) files containing the contents of each page, _layout HTML files which are referenced in each to determine how the contents are presented, and _include HTML files which are referenced in either the layout or content files to display some extra piece of the website (e.g. a navbar or a commonly-occurring button or icon). The resulting file structure of the site will be discussed further in “Repository Structure.” It requires Ruby (installation information here) and RubyGems (which should be included with Ruby) to install via gem install bundler jekyll in the terminal. After installation, the site can be built by opening the repository folder in the terminal (or cd-ing into it; this is already done if you’ve opened the entire folder in VSCode, so you can use the terminal tab at the bottom) and running bundle exec jekyll serve. I’ve used some additional plugins on the site, so it’ll throw an error on the first build and prompt you to install those; from there any work with Jekyll should be smooth sailing!

Tailwind (https://tailwindcss.com/) simplifies writing CSS for the site by supplying a set of classes with short and easy-to-remember names. It can be installed as a CLI tool with npm install tailwindcss @tailwindcss/cli. (This uses npm, so unfortunately you’ll need to install Node first: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) To use it on the site, just open the folder in another terminal tab and run npx @tailwindcss/cli -i ./assets/css/initstyles.css -o ./assets/css/finalstyles.css --watch. It will then replace the “@import "tailwindcss";” in the initial styles file and watch for future changes to re-run the command in that terminal instance.

2.1.1 TLDR (“Just give me the instructions already!”)

  1. Create a Github account
  2. Download and install Github Desktop and Visual Studio Code
  3. Open Github Desktop and follow the instructions to log in and clone a repository. Use the link https://github.com/alabenian/mobilebaydsa or alabenian/mobilebaydsa.
  4. Open Visual Studio Code, and within it, open the folder you created by cloning the repository in the previous step. Tell VSCode that you trust the author, then find the “terminal” tab at the bottom of the window.
  5. (Windows) Download and install a Ruby release from https://rubyinstaller.org/downloads/.
  • (Mac) Use Homebrew (if you don’t already have it installed, first run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)") to update your Mac’s built-in installation of Ruby: brew update and then brew install ruby in your VSCode terminal.
  1. (Windows) Download and install a release of NVM Windows from https://github.com/coreybutler/nvm-windows/releases. Then run “nvm install latest in your VSCode terminal.
  • (Mac) Run the NVM install script: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
  1. Still in your VSCode terminal, run these commands:
  • gem install bundler jekyll
  • npm install tailwindcss @tailwindcss/cli
  1. Mouse over to the “+” button to the right of the terminal and click it to create another terminal tab. In each of the tabs now open, run one of the following commands:
  • bundle exec jekyll serve – This will prompt you to install some additional plugins. Afterwards, it will build and serve your website to some localhost port. Take note of the “server address” it gives you immediately after this, open it in your browser, and bookmark it if necessary for future reference to see the effects of your changes.
  • npx @tailwindcss/cli -i assets/css/initstyles.css -o assets/css/finalstyles.css --watch – This will add any Tailwind classes used throughout the website to the base stylesheet, generating finalstyles.css, which is used as the main stylesheet for the whole website.
  1. Start working!