Why You Need a Portfolio Website

And how to make one

Prof. Josh Brake

2024-11-11

You need to maximize your luck surface area

A mathematical illustration of luck surface area.

Modified from “Let It Rip”.

A portfolio offers you an outlet to share your work

A portfolio has many benefits:

  • The best credential (look what I’ve done)
  • A demonstration of growth
  • A place for others to find you

Components of Your Portfolio Website

At minimum, your portfolio website should have:

  • Home/About Me page
  • Links to other profiles on the web (e.g., LinkedIn)
  • A copy to a PDF of your resume
  • A page with a list of your projects

You could also consider including some other things:

  • Blog
  • Page with hobbies

Where to start

  • Brief biographical blurb
    • Who are you?
    • Where did you come from?
    • What is your personal mission (what you do now) and vision (who you want to become)?
  • Projects
    • List of projects you’ve worked on
    • A short description of the project
    • Photos/videos

How to make your website

There are many different options you could use to create your portfolio website.

  • Paid vs. Free
  • Fancy vs. Fragile

Quarto

  • What is Quarto?
  • Why should you use Quarto?
  • How do you get started with Quarto?

Setup

  • Download Quarto
  • Set up Github
  • Getting your github.io site setup

The Structure of a Quarto Site

  • _quarto.yml
  • index.qmd
  • Other pages and folders
project:
  type: website

website:
  title: "Quarto Portfolio Website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: projects/
        text: Projects
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

The Quarto Development Flow

  1. Write code
  2. Preview
  3. Revise
  4. Render
  5. Publish

Building Your Site

Steps to build your portfolio

  1. Create a new quarto project
  2. Configure _quarto.yml
  3. Create structure
  4. Add files and write pages
  5. Render locally
  6. Commit to version control (Git)
  7. Publish to Github Pages

Create new quarto project

  • Create a new folder <github_username>.github.io.
  • Open VS Code, open that new folder you created, and open a new terminal (Terminal > New Terminal).
  • Run quarto create.
  • Follow the prompts to select the options as shown below. Note that ./ will create the project in your current directory.
(base) joshbrake@computer % quarto create
? Create › project
? Type › website
? Directory › ./
? Title (./) › Demo
Creating project at /Users/joshbrake/dev/temp/:
  - Created _quarto.yml
  - Created index.qmd
  - Created about.qmd
  - Created styles.css

Render your new site

Once you create your Quarto project you can preview it immediately to see what it looks like.

quarto preview

By default, this will render the entire site and then open a browser to preview it. If you want to preview a specific file, you can include it after the command. (e.g. quarto preview <filename>.qmd)

Customizing your site

Next, we’ll customize the site.

  • Modify file structure to add pages
  • Modify _quarto.yml

Modifying the file structure

You can organize your files however you would like, but choosing a regular file structure will be very helpful. I recommend the following general structure.

  • .gitignore file: Includes the files to leave untracked in version control.
  • blog.qmd: will load blog post from posts/ folder
  • _site/: auto-generated by Quarto, you don’t need to create this folder. You should add it to your .gitignore.
  • projects/: folder to organize projects.
  • projects/index.qmd: page to display and list projects.
  • images/: folder(s) to store images for your site and pages. Best to keep organized in the relevant folder (e.g., per project).

Sample project directory structure

├── .gitignore
├── README.md
├── _quarto.yml
├── _site
│   └── ...
├── blog.qmd
├── images
│   └── headshot.jpeg
├── index.qmd
├── posts
│   └── first-post.qmd
├── projects
│   ├── example-project-1
│   │   ├── images
│   │   │   └── e155-kit.jpeg
│   │   └── index.qmd
│   ├── example-project-2
│   │   ├── images
│   │   └── index.qmd
│   ├── index.qmd
│   └── template
│       ├── images
│       └── index.qmd

Creating your homepage

  • Open index.qmd at the project root. This is your homepage.
  • Create the following frontmatter structure, replacing the information with yours.
  • Write a brief biographical blurb for yourself (you can easily change this later).
  • Run quarto preview to check your updates.
---
title: "Josh Brake"
image: images/headshot.jpeg # replace with the link to your headshot
about:
  template: jolla # see additional templates here https://quarto.org/docs/websites/website-about.html
  links:  # add links to your various social profiles
    - icon: substack
      text: Substack
      href: https://joshbrake.substack.com
    - icon: linkedin
      text: LinkedIn
      href: https://www.linkedin.com/in/jbrake
    - icon: github
      text: Github
      href: https://github.com/joshbrake
---

Enter your biography blurb here.

Add a project page

Next let’s add a project page.

Create a new subfolder under your projects/ folder. Name it a descriptive name for one of your projects (e.g., E80-robot/). Try to avoid spaces. Create two additional items within the folder:

  • images/: this will hold the images for your project.
  • index.qmd: this will be the project page.

After you finish, your directory structure should look like what’s on the right.

.
├── projects
│   ├──E80-robot
│   │  ├── images/
│   │  └── index.qmd

Writing a Page

All documents in Quarto are written as Markdown. It’s an easy format for writing text. Here are a few specific formatting tips to keep in mind.

  • HTML Heading levels: # -> <h1>, ## -> <h2>, ### -> <h3>,
  • Images: ![alt text](link)
  • Figures: ::: {#fig-<label-here>} :::
  • References: @fig-<label-here>
    • Figures
    • Headings
  • Code blocks: Enclose between triple backticks ``` ```

Creating a page for your project

Open the index.qmd page you just created inside your E80-robot folder and add the following.

Feel free to customize the headings as you like.

---
title: E80 Robot
author: Josh Brake
date: 2024-11-11
image: images/ # A url to image here.
description: This is a description # Short description of the project to be shown on overview page.
---

## Problem Statement

## Project Goals and Objectives

## Process and Approach

## Results

## Impact and Reflection

## Future Improvements

Adding text and images to your project page

Now we’ll add some text and images to our project page. First, copy a photo into the images/ subfolder. Then, edit the index.qmd page inside your project folder to display it.

...

## Problem Statement

::: {#fig-replace-with-label}
![Alt text here](images/dana-point.jpeg)

Optional figure text here
:::

@fig-replace-with-label shows an image of the dock at Dana Point.

...

See Quarto docs on figures for more information.

Bonus tip: You can style inline with css by putting the css in curly braces after the image link. For example, to change the width to 400 pixels:

![](images/dana-point.jpeg){width=400px}.

Creating projects overview page

The last thing we need to do before we publish our site with the minimal setup is create a project overview page. To do this, open projects/index.qmd and add the following text.

---
title: Projects
---

## E80 Robot

::::: {.columns}
::: {.column}
E80: Experimental Engineering is a sophomore engineering class at Harvey Mudd College.
Check out the robot I built by following the link [here](E80-robot/).
:::
::: {.column}
![](E80-robot/images/)
:::
:::::

## Project #2

Customizing _quarto.yml

After you add the pages

project:
  type: website

website:
  title: "Quarto Portfolio Website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: projects/
        text: Projects
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

Quarto Publish

Once you have your site ready and it’s rendering properly locally, it’s time to publish it to the web. To do this, we’ll use the quarto publish command. Details can be found here.

First we need to commit all of our changes to the Git repository. To do this, open Github Desktop, add all the files for your website, and then commit them. Once you do this, push to the remote.

Setting up Github pages

Then, we need to setup the Github repo to render the site from the gh_pages branch.

If it’s a fresh directory, you won’t have a gh_pages branch. So, first we need to create an empty one. To do so, run the following code:

git checkout --orphan gh-pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages

After you finish this, go back to the main branch by running git checkout main. This must be completed before you run quarto publish!

Publishing

Once you’ve completed these steps, login to your Github repository and configure Github Pages to render the site from the gh_pages branch.

Taking Your Portfolio to the Next Level

Buy Your Own Domain Name

A personal domain is well worth your investment. It will cost you at least $20-40 a year, but it will give you a nice spot for your web presence and also a nice email.

  • Go with a .com if it’s available. (could also consider .me as well)

Hosting

The domain name just gives you a DNS entry but you also need a server with an IP to point that DNS entry to. A few options:

  • Host on Github pages and direct your domain there.
  • Self host
  • Host with a conventional web hosting company
  • Host on a VPS

Some other tools

VS Code tools

  • Markdown extension: Can help you easily paste in images, automatically update filenames when you change them.
  • Snippets: pieces of code that template commonly used code constructs.

Conclusion

A mathematical illustration of luck surface area.

Modified from “Let It Rip”.