Our website, http://wadhwalab.com, is a GitHub Pages site built with Jekyll and Bootstrap, originally pulled from D. Allan Drummond's website.
What follows is a basic guide to making modifications to the site, focused on adding typical content.
You will need working knowledge of Git, GitHub, Markdown, HTML, and (possibly) a few basic Unix commands. You will need Jekyll (which in turn requires Ruby and RubyGems). If you need help getting set up, ask someone who is already up and running.
To execute Git and Unix commands on your computer, you will need a terminal (aka command prompt, command shell, and command line). Here are some options:
- For macOS:
- Built-in Terminal. Press
⌘ command+spaceand type terminal. - iTerm2, which can be integrated with Zsh and Oh My Zsh for some great features.
- Built-in Terminal. Press
- For Windows:
- Windows Terminal, integrated with Oh My Posh for some great features.
- Git Bash. It is built into Git for Windows.
- For Linux users:
If you have all the software installed and a basic knowledge of the tools, it is time to get started!
Note: While I describe the following using several command line tools, almost everything here can be achieved using a good GUI-based editor like VS Code. Indeed, this is my own preferred tool.
If you're a member of the Wadhwa Lab, please contact Navish to request collaborator access to the website repository. Once the access is granted, you are ready to edit the site.
Clone the repository, i.e., make a local copy on your machine:
git clone https://github.com/navishwadhwa/navishwadhwa.github.io.git
To start, you should be on the main branch. In most cases, this should be the only branch in the repo when you begin working. Enter the repo using cd and "checkout" the main branch.
cd navishwadhwa.github.io
git checkout main
You will now create a new branch for the changes you want to make to the website.
git branch <feature>
git switch <feature>
Here, "feature" can be anything from "news" for adding a news item, to "typo" for fixing a typo, and so on. Once on this branch, go ahead and make changes to the website (see below). Be sure to stage and commit your changes regularly and push these changes to remote, i.e., the GitHub repo.
When you are ready to publish your changes, you would want to create a pull request to merge your changes into the main branch. To do so, head over to the GitHub repo and create a pull request. Someone else will then review your changes and potentially ask for some tweaks. Once the pull request is closed and the branches are merged, your changes will go live in a few minutes.
Once the pull request is closed and your changes are live, the feature branch has served its purpose. At this stage, you should delete the feature branch on GitHub as well as on your computer.
To delete the branch on your computer, run git branch --delete <feature>. Then run git branch -a to verify the feature branch is deleted. To clean up remote branches that no longer exist, run git fetch -p.
Let's assume you're familiar with HTML pages. A site is a collection of HTML pages. For our site (and many others), there are page types, like a paper page, or a lab member page, which are the same in design but different in content. In the web-accessible site, these are indeed different pages. However, as you might hope, they are generated from a single template file filled in with information from many paper- or member-specific data files. This generation is done every time the site changes; it is handled by GitHub Pages, the service we use.
The template files are weird-looking HTML files residing in the _includes/themes/lab folder.
For most common actions, such as adding a lab member, a new paper, or a news item, you will create a new Markdown file in the proper location, name it properly, and fill in the required fields. The best way to do this is to copy an existing item, change the name, and change its content.
For example, suppose you want to add a news item, to appear on the front page. To do this, go into the news/_posts folder. Copy one of the existing items into a new file named with today's date and a brief title. Here is an example doing this using command line,
cp 2020-07-30-navish-gets-k99.md 2023-06-09-amazing-discovery.md
The date string in the file name is used by the generator to date and to order the items. Now edit the new file in the editor of your choice to make the content what you want. After editing, it should look like this:
---
layout: news
title: "Amazing discovery"
author: "Navish Wadhwa"
author_handle: "nw"
image: /assets/images/news/news-image.png
category: news
tags: [breakthrough]
---
Lab member ABC made the amazing discovery XYZ, published today in journal [your favorite journal](http://journal.com/content/doi)!
Add the file to the repository:
git add 2023-06-09-amazing-discovery.md
And, when you're happy with it, commit and push:
git commit -m "added news about discovery"
git push
The same basic process is used to add papers, team members, etc.
Once your edits are done, preview the site. Generate the pages and start the private webserver:
bundle exec jekyll serve
...and then open the local test site, http://127.0.0.1:4000. Look at anything you've changed and make sure it works as intended. You can continue making further changes while viewing them live in local test site. Just remember to stage and commit regularly.
Once everything looks good, follow the process described above to create a pull request and merge the branch into main.
Changes won't be immediate, so wait a minute or two while GitHub's servers regenerate the site and publish it. Check to make sure the public site http://wadhwalab.com looks the way you intend.
Finally, delete the feature branch and call it a day.
To go to the next level, familiarize yourself with HTML and CSS. Fonts, colors, spacing, and similar stylings are separate from the template pages. Like most sites, these use Cascading Style Sheets (CSS). These and other more advanced settings are found in \assets\themes folder.
See Issues on the site.