EVE Lab Website

Please see below for instructions on how to install, build, and modify the EVE website

• Installation
• How to Edit Jekyll Sites
• Changing People Information
• To Do List

This guide will help you set up the EVE Lab website on your own computer using micromamba. This will allow you to edit and preview the site locally before pushing changes. Please always preview changes before pushing!

Open your terminal and create a new environment called jekyll-lab (or any name you like) and activate:

micromamba create -n jekyll-lab -c conda-forge ruby=3.4.1
micromamba activate jekyll-lab

Install the version of bundler used in the project, and check it's installed correctly:

gem install bundler -v 2.6.2
bundler -v

Install necessary compilers on linux:

micromamba install -c conda-forge gcc_linux-64 gxx_linux-64 pkg-config make libffi openssl

On MacOS:

micromamba install -c conda-forge clang_osx-64 clangxx_osx-64 pkg-config make libffi openssl

Clone this repository to your local drive and enter it:

git clone git@github.com:hodcroftlab/hodcroftlab.git
cd hodcroftlab

Now install all the required Ruby gems (including Jekyll):

bundle _2.6.2_ install

jekyll serve --incremental

Some websites suggest to use bundle exec jekyll serve but this has never worked for Emma.

Note that using --incremental means the site will live-rebuild any pages that you change (and save) locally.

If you want to view blog posts that are dated in the future (e.g. that we expect to make live tomorrow), use the --future argument to allow it to display blog posts after the current date.

To view the site, navigate to http://127.0.0.1:4000 to view. Note you can only view the site locally while this is running. To stop running, use CTRL+C. To see changes, refresh the page locally. (Be sure you've actually saved the page, or it won't rebuild and show the change!)

If changes are not showing locally after refreshing (particularly after adding new pages), you may need to do a full clean and rebuild. To do this, clean the built files using

rm -rf _site .jekyll-cache .sass-cache

Then serve the website with the first command again.

Remember, it's good practice to view any changes locally (see above) before pushing! This ensures you haven't broken anything else and that the changes look as you expect. For very small changes (fixing typos, adding sentence) it's not always necessary to check locally - but be careful!

If making small edits, as long as you've checked locally, it's ok to push directly to master. However if proposing larger changes, make them on a branch and submit a PR, so others can check it locally & ensure they like the change (and that it works as expected) before making changes to the website. (If necessary, please flag your PR to ensure others see it, for example, in the Slack!)

Once you push a change to the master branch (or merge a PR into master), Github will automatically re-build and deploy the live site.

Editing Jekyll sites takes some getting used to. The way they work is that base files are built and generate more 'recognizable' HTML files (and accompanying files) that are what are actually served as a website. These 'final' files are rebuilt every time you build the site, but stay the same between builds (hence why this is called a 'static' website - no information is generated 'only the fly').

In this site, the 'build' files are in the folder docs (the name of the original theme). Never modify files in docs to try and make a change! It will simply be overwritten the next time you build the site!

In general each page is made from a union of a few others pages. For example, our index.html simply pulls information from other pages - intro.html, projects.html and more (see the source of the page). Data is generally stored in a couple of places, then how that is formatted is stored elsewhere.

Some examples:

Information on people is generally in _data/team.yml and _people/<name>.md- these two are then pulled together to make everyone's individual page in _layouts/person.html. However, this data (at least the data from team.yml) is also used on index.html (via _includes/team-preview.html) and _pages/about.html to make the little rows of circle-faces.

Projects and collaborations are easier - the page format is in _layouts/collaboration.html and _layouts/project.html and the information is on individual pages in _collaborations/ and _projects/. (The layout for displaying all of them together in the 'View All' pages is in _pages/collaborations.html and _pages/projects.html.) Note that we specify what kind of layout the project and collaboration pages should use in the header (ex: layout: project).

Luckily you shouldn't have to worry too much about layout changes (let Emma know if you think something could be improved - or at least ask her before attempting!).

Generally, you should focus on editing the .md files to add information. To see how to edit your own or others personal pages, see changing people information.

To edit a project or a collaboration, just find the corresponding .md file in _projects/ or collaborations/. To change their photos, add the image to assets/images/projects or assets/images/collaborations and modify the image: property in the .md file. (Please don't modify the logos without talking to Emma first.)

To add a project or collaboration, create a new .md file in the correct folder, following the format of existing files (don't forget an image, and for collaborations, a square, grayscale icon!). Then add a link in the menu at the top of the website by adding a new entry in _data/nav.yml.

Ensure you add the name of anyone else involved in the project/collaboration, and check to see if you should add this project/collaboration to anyone's page! (Via their _people/<name>.md file.)

There are two places to update information about a person:

_data/team.yml is the list of people who will appear on the About and Index (front) pages, and also includes:

• Social media info (supported: ORCiD, Google Scholar (gscholar), Bluesky, Linkedin, Twitter, Mastodon, Facebook, Github)
• Image on the About/Index page
• Description on the About/Index page (PhD student, etc) (designation)
• Interests that will appear on your main page

_people/<name>.md contains:

• Photo that will appear on your page
• Quotes that will appear on the /people page (on mouseover) (can have more than one, see Emma's page for an example)
• 'Role' for sorting on the /people page (ex: member, alumni, visitor)
• Projects you are involved in (appears on your page) (copy this exactly from _data/nav.yml!)
• Text that you write about yourself, as the main content

To change your photo, the easiest thing to do is to just replace the photo of yourself assets/images/people and ensure it's named the same! Ensure your photo is square (or it won't crop correctly) and isn't huge (will load slowly). Resize if you need!

To change your 'socials' (also ORCiD/GScholar) you can generally just add a new entry to your section of _data/team.yml. Talk to Emma about adding any others!

To add to the 'Tools & Resources' page, you should only have to edit the _data/tools.yml page. Do be sure to add it to the right category, or add a new category if necessary (maybe ask Emma if unsure). You can add a link to the tool (url), a link to the github (github), or both.

You can either choose a FontAwesome font (see "EV-D68 Reference Converter"), or add a (very small) image to /assets/images/icons and use this instead (see "EV-D68 Nextstrain Build").

Create blog posts following the format of existing posts in the _posts folder (and name the file starting with the date of the post). Fill out the title, date, and descriptions in the header. If you'd like to have multiple authors, use the format (Be sure to match the name format used in the people files)

authors:
  - nadia-neuner-jehle
  - emma-hodcroft

Throughout the site we often make use of 'FontAwesome' icons for links and for decorating cards, menus, and etc. We used (pre Aug 2025) to use FontAwesome 4.7 (list of icons here) - as of 4 Aug 2025, we've moved to FontAwesome 6.5.2 (see _layouts/default.html). Note that we do not have Pro - only the basic icon set. To add a new icon, see this list to see what's available.

• Add page for PDN as Collaboration
• Create a way to have subprojects (for specific projects within the larger groups)
• Should we upgrade to a newer version of Ruby/Gems?