Building our own research porfolio

In this section we will all build and publish our own website with the aim of giving you:

1. Hands-on experience with writing the Quarto documents required for a website.

2. A website that highlights your capabilities as a researcher and bioinformatician.

Aims

• Learn how to publish a website.

• Gain experience with Quarto, explore options around format, theme, styles.css, etc., to create a polished website.

• Pin a repo to showcase your capabilities.

• Gain confidence in working publicly.

* As an alternative to creating a research portfolio website, you may instead choose to focus on creating a website that documents one of your particular projects, or some other form of website. While we recommend the concept of a pinned github repo to highlight your abilities as a researcher and bioinformatician, how you do this is up to you.

Why a portfolio website?

If you want to progress in bioinformatics, you should assume that people (future employers) will look at your github. Having a set of tidy repos that document your workflow is the minimum you should aim for. In addition to these tidy repos, we can build a single repo that directs and guides viewers through our github and highlights our key skills.

Aside from github repos it can be useful to create websites as a way to market either yourself and your work, or the work of your lab group. Quarto can make this easy. Jadey Ryan has a great website that really showcases what a Quarto website can look like.

To get a better understanding of why I am recommending this and what we are trying to do, I recommend this talk from posit::conf(2024) titled “Github - How to tell your professional story”. In this talk, Dr. Abigail Haddad outlines how Github can be used to demonstrate not just the raw coding skills you use frequently, but also the auxilliary skills that define how you work - your problem solving skills, your practices, and how you communicate.

We are going to take some of the advice from that talk, which says that all of your github should be used to actively demonstrate your skills and tell your story, and we are going to compress it down to a single github repo which will convey (or at least introduce) your story. We will Pin this repo so that it’s the first thing people see when they visit your github page, and publish it as a working website so that you also have a link you can drop into LinkedIn or Bluesky posts, incorporate into your email signatures, whenever you feel it’s appropriate to do some self-marketing.

Initial setup (5-10 minutes)

Using skills from yesterday and today’s workshops:

• Initiate a new, public github repo with a name like Work Portfolio or equivalent.

• In RStudio, start a New Project and use the Version Control option to link it to the new repo.

• Create three .qmd files. For each file, set the YAML header to include an appropriate title and add at least one header and a piece of sample text to each document:

  • index.qmd. Index.qmd will work as the landing page for the site, and could include something like the short blurb found at the top of a CV.

  • portfolio.qmd. Portfolio will contain hyperlinks to your work - either to other github repos, publications, google scholar account, LinkedIn account etc., (it will be the definitive, exhaustive set of your work).

  • research_focus.qmd. Research_focus.qmd will include a written statement about your focus as a researcher.

* Note these initial files are templates only, and will be populated later.

• Create a _quarto.yml file using the template from the previous section. Under contents, include index.qmd first, then portfolio.qmd and research_focus.qmd.

Refining the site

Here we will look at a number of options through the _quarto.yml file to improve the look of the website.

Improved navigation and layout

Sidebar navigation

In the last section we added a navbar along the top of the page for website navigation. An alternative to this is sidebar navigation:

• In the _quarto.yml document, replace ‘navbar:’ with ‘sidebar:’.

• Add a new line below sidebar, indent and add style: “docked”.

• Add a new line and (same indentation level as style, because it is an argument under sidebar) add contents:, then add individual .qmd documents with text and href as before.

Sections

We can group pages under a header in sidebar navigation. Clicking on the header will open a drop-down menu. Each section can be given it’s own name, and can have any number of individual pages nested below it through the “contents:” key.

Sections are very useful for e.g., a website that focuses on discrete aspects (two day protocols, wetlab and drylab sections etc.,)

Example sidebar and section .yml

Sidebar and sections example

Adding personal details: github icons, footer, light and dark

Site icons

We can add a range of icons to our navigation menu and provide links for these icons. This provides an easy and clear way for site visitors to view your other, more commonly used accounts. Commonly used icons include github/linkedIn/bluesky, with thousands of icons available for use. Add the code below to a new line in the website section of the _quarto.yml file. Note that navbar should be at the same indentation level as sidebar. You can swap the href link (which is currently to the generic github site) to your own github.

navbar:

right:

  - icon: github

    href: https://github.com/

    aria-label: GitHub

Footer

Add a footer with:

page-footer:

center:

  - text: "Built with love and Quarto"

  - href: https://quarto.org

Themes light and dark

In addition to selecting a single theme as we have done in the previous section of this workshop, we can enable both a light and dark mode using themes. The easiest way to do this is to choose the simple themes “flatly” and “darkly”, but you can select any themes you prefer.

To do this, under theme, add two new lines with the key-value pairs “light: flatly” and “dark: darkly”. After rendering we can now switch between light and dark modes.

styles.css

In addition to the pre-built format that themes can provide we can also customise our sites with a styles.css file. The .css file is a “Cascading Style Sheets” document, which can be used to override all of the Quarto defaults for HTML documents. The .css file is used to manipulate fonts, choose colours, layout, background for code cells, side and navbar aesthetics, table text alignment - almost every visual aspect can be changed with a styles.css file.

The styles.css file is written in css - it is not Quarto specific, and requires reasonably detailed knowledge. I recommend using templates sourced online or chatGPT equivalents for building a styles.css template which you can then work from. Using chatGPT I selected colours (blue and gold for Otago), specified that I wanted those to be gentle (not harsh, lower contrast) and asked for a clean, clear look. I took the template and added it a new document call styles.css.

Styles.css is stored in the top level of the directory. In the _quarto.yml document under format, I added a new line at the same indentation level as theme and added “css: styles.css”.

Pinning a repo and publishing the site using github

On the github website you can pin up to six repos as visible on your main landing page, with the remaining repos being visible under the repos tab. Once your research portfolio website is underway I recommend pinning it, alongside your most completed and well-documented repos, so that they will be the first thing visitors will see.

To publish a website - that is, to take it from the local-only html file to a hosted site that is accessible via url - there are a number of options. Today we will focus on publishing through github pages. Within github pages there are three options for publishing (render to docs and publish, using the quarto publish command, or using a Github Action). We will use the simplest option, render to docs and then instruct github to publish from the docs directory.

Setting up

In the _quarto.yml file, make sure that we have “output-dir: docs” under project. Quarto render will then output all files to the docs directory.

We need to add a specific file that tells github pages not to do additional processing of our site (github has built in methods for publishing, which we do not want to use here). Under the Terminal tab in RStudio, run “touch .nojekyll”. Just like how the underscore at the start of a _quarto.yml file means the file is not rendered, starting with a “.” means that the file is not rendered and is instead treated as a high-level argument.

Render, add, commit, push

While still in the Terminal window of RStudio, run:

quarto render

git add docs

git commit -m "publish to docs/"

git push

Our new rendered docs should now be stored safely in our repo.

Deploy from main/docs

Navigate to the github repo for the page you wish to deploy. Under Settings > Pages, use the dropdown menus under the Branch header to select “Main” branch, and then switch the directory from “root” to “docs”. When ready, click “Save”.

The page should refresh with a new note saying “Your Github pages site is currently being built…”.

Deploying the github page

Refresh the page to see the url for the new site and a button to Visit the site. Copy this url, return to the main page for the repo, and use the buttons on the github site to edit the About and/or Readme. Alternatively, back in RStudio open the README.md file and add the url there.

Summary

You can reasonably expect people to look at your github repos. Creating a repo to guide viewers through your portfolio of research is a a good way to influence what people will see.

With quarto we have a great level of control over the documents we create with arguments in the _quarto.yml file, through the use of themes, and a dedicated styles.css file.

There are multiple ways to freely publish your documents as websites. Github pages works well with quarto docs and the method shown here is simple and easy to follow.