Building our own research portfolio
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, we 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
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, and select where you want the directory to be (e.g., select ‘Desktop’, and your new directory will appear on your desktop)
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.Create a
_quarto.ymlfile using the template from the previous section. Includeindex.qmdfirst, thenresearch_focus.qmdand thenportfolio.qmd.
Note: these initial files are templates only, and will be populated later.
Save all four files and click “Render” in RStudio. You will now have created a rudimentary structure for your work portfolio website.
We encourage you after the workshop to spend some time developing your research portfolio website, populated with your own real information.
Here as an example, we have created a website as if written by the scientist Dr Barbara McClintock.
You can use this text to populate your own if you’d like to use an example for now:
Hint: The image in index.qmd will not display unless you download it from the given link and put it in a dir called images. The site will render regardless.
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
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.,)
styles.css
In addition to the pre-built format that themes can provide we can also customise our sites with a styles.css file. This 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. We recommend using templates sourced online or chatGPT equivalents for building a styles.css template which you can then work from.
Styles.css is stored in the top level of the directory. In the _quarto.yml document under format, we can add a new line at the same indentation level as theme and added css: styles.css
format:
html:
css: styles.cssPublishing the site using GitHub Pages
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.
1. Setting up
In the
_quarto.ymlfile, make sure that we haveoutput-dir: docsunderproject. 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 .nojekyllThe file is not rendered - starting with a . means that the file is not rendered and is instead treated as a high-level argument.
2. Render, add, commit, push
First, save all your open .qmd files. Then, click the ‘Render’ button on every single .qmd file. This will create a html file in docs/ for each qmd file.
While still in RStudio terminal, run:
git add . (The . adds everything, alternatively type: git add docs)
git commit -m "publish to docs/"git push(If you get an error message here, you might need to type git push origin main)
Our new rendered docs should now be stored safely in our repo on the GitHub server.
Yes there is!
There are two ways you could do this:
1. Save all files, close RStudio, re-open RStudio.
a) You will now see a tab appear that says ‘Build’.
b) Click the button that says ‘Render Website’ and all your qmd files in the directory will be rendered. The qmd files don’t need to be open in RStudio. Note that this only works if you made an RStudio project first (we did this in “Intial setup”).
2. Render from the command line
a) Make sure you have Quarto CLI tools installed first. Type quarto --version to check.
b) Type quarto render in terminal. All qmd files will render. You can confirm this by checking that recent html files have appeared in docs, and by running quarto preview in terminal to confirm your website looks how you expect it to.
3. 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…”.
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.
Explore and share your now live portfolio webpage! 👏
4. Pin your repo
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 we recommend pinning it, alongside your most completed and well-documented repos, so that they will be the first thing visitors will see.
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.