Personal Website Workshop

Department of Statistics

Computing Committee

​

​

Benjamin Osafo Agyare

and

Jesse Wheeler

​

09/05/2024

Why Academic Website/Portfolio?

Market Yourself/Learn Personal Branding

Showcase your projects and Publications

Maintain Academic Blog/Share Knowledge

Repository for Resources

And Many More…

Example Contents of Academic Website

Header, Footer and Navigation Bar

Favicon

Introductory Statement (About Me)

Experience (Teaching and Working)

Research/Projects/Publications

News/Upcoming Talks/Events

Miscellaneous (Awards, Service, Contact Forms)

Website Basics

• Websites are typically html files (and embedded languages like javascript for interactivity).

​

• Generally, no one actually writes html. Instead, it is typical to use some software to write the html.

​

• To make your website publicly visible, you need to host your website on a server.

HTML Source options

Server / Host options

Both

• Hugo / Hugobox
• Jekyll
• Quarto
• HTML from scratch 😟
• … many more

• Netlify
• GitHub Pages
• Google Sites
• Umich Personal Space
• … many more

• Owlstown
• Wordpress
• etc.

HTML Source options

Server / Host options

Both

• Hugo / Hugobox
• Jekyll
• Quarto
• HTML from scratch 😟
• … many more

• Netlify
• GitHub Pages
• Google Sites
• Umich Personal Space
• … many more

• Owlstown
• Wordpress
• etc.

Quarto / GitHub pages

Requirements

For this workflow, the following things are required: �

• Having Quarto installed (free) �
• Have a GitHub account (free), and some familiarity with Git.�
• (Optional) Have Rstudio installed (free)

Workflow

• Build a website locally using Quarto

​

• Deploy website on GitHub pages

​

• Customize Website

​

• (optional) Automate the procedure using GitHub actions

​

Quarto Introduction

Quarto is an engine built by Posit (company formerly known as RStudio) that can run Jupyter notebooks, R markdown files, and be used to develop websites.

• Advantages: Free, easy to use, integrates well with R / Python / LaTeX, seamless integration with other GitHub projects. �
• Disadvantages: Fine-level customization of websites is challenging.

Getting Started

There are three ways to initialize a Quarto website�

• Command line:

quarto create project website <mysite>�

• VS Code�
• RStudio (Live demo of this here)

RStudio

The Quarto Website will be an RStudio “project”.

• In the top-right corner of RStudio, click the project drop down menu and select “new project”. �
• Pick “New Directory” -> “Quarto Website”�
• Chose local directory for website, and pick a name�
• If using GitHub pages, try: “<git-user>.github.io” as a name
• You also need this to be a Git repository. You can initialize manually or by checking “Create a git repository”

​

​

This created a new directory, called <website-title>, and auto-generated a few files:

​

​

<website-title>� — _quarto.yml - Configuration file

— about.qmd - “About page”

— index.qmd - Landing page

— <website-title>.Rproj

— styles.css - Custom CSS (empty)

— (.git) - (Hidden Git directory)

To render the website: in RStudio, click the “Render” button. Alternatively in a terminal, use the command: quarto render in the correct directory.

​

<website-title>� — _quarto.yml - Configuration file

— about.qmd - “About page”

— index.qmd - Landing page

— <website-title>.Rproj

— styles.css - Custom CSS (empty)

– _site

– about.html - HTML about

– index.html - HTML index

– …

Publishing Website

To publish our website, we will use GitHub Pages. Full instructions can be found here (both options).

There are two main approaches:

• Render site locally, commit website and push to GitHub, tell GitHub which folder contains the rendered site.
• Easiest approach, but can result in messy Diffs / git commits. �
• Commit source code, use “quarto publish” or GitHub actions to deploy website on gh-pages branch
• Cleaner diffs, more elegant, more automated, slightly harder.

​

Easy version: main branch

• Change _quarto.yml to render to “docs” folder.

project:

type: website

output-dir: docs

• Render website locally
• Either push the render button, or run:

quarto render

• Add an empty file called .nojekyll

Easy version: main branch

• Commit all changes to website
• git add .
• git commit -m “my first commit” �
• Push commit to GitHub
• Create a new repository on GitHub
• Add remote to your local copy that links to GitHub account:

git remote add origin <insert address here>

• git push -u origin main
• Now we need to tell GitHub where the website is located.
• Settings -> Pages, set branch (main) and folder (docs).

Now you should have a live website, located at either:

• <git-user>.github.io (if your website name is your git user name)

​

• <git-user>.github.io/<website-name> (if your website name is NOT your git user name).

​

• To update your website, you can modify the source files locally, and commit then push your changes to GitHub, and the website will update accordingly.

​

​

_quarto.yml

This YAML file is the website configuration file. It contains basic settings for aesthetics and navigation for your website.

There are three main components of this file:

• project: describes how the website is built �
• website: controls basic website navigation �
• format: controls overall aesthetics and style of website.

index.qmd and .qmd files

The index.qmd file is used to create the landing page (index.html) for your website (i.e., default page when someone enters your site).

• .qmd files are extended versions of R Markdown (.Rmd) that are provided by Quarto�
• When your website is rendered, all .qmd files are rendered by default.

Customization

Your new website is easy to customize using some built-in templates. If you want to go outside of these templates, it gets a bit harder. Here are some good resources:

• Quarto Website Documentation�
• An additional tutorial for Academic Websites.
• This tutorial is very similar to these slides, but there is additional information starting with the section “Where you should start changing stuff”

Introduction to Hugoblox/Netlify

(Practice)

Toolkit

GitHub Account

Netlify Account (created on-the-fly)

Getting Started

Getting Started

Choose Academic Template or another

Getting Started

Choose Academic Template or another

Select Deploy to Netlify:

Getting Started

Choose Academic Template or another

Select Deploy to Netlify:

Getting Started

Choose Academic Template or another

Select Deploy to Netlify:

Getting Started

Connect to GitHub

Getting Started

Save and Deploy

Getting Started

Confirm that it is deployed

temporary site name

Getting Started

Change Site name

Getting Started

Change Site name ct’d

Getting Started

Change Site name ct’d

Getting Started

Visit Documentations Doc 1 and/or Doc 2 to edit content (editing files directly via the GitHub repo used is recommended!! See next slides)

Site Content

Site Structure

There are 4 main folders for Hugo-based sites (FOUND IN THE GitHub REPO USED):

• content/ for your Markdown-formatted content files (homepage, etc.)
• _index.md the homepage (Hugo requires that the homepage and archive pages have an underscore prefix)
• assets/
• media/ for your media files (images, videos)
• icons/custom/ upload any custom SVG icons you want to use
• config/_default/ for your site configuration files
• hugo.yaml to configure Hugo (site title, URL, Hugo options, setup per-folder page features)
• module.yaml to install or uninstall Hugo themes and plugins
• params.yaml to configure Hugo Blox options (SEO, analytics, site features)
• menus.yaml to configure your menu links (if the menu is enabled in params.yaml)
• languages.yaml to configure your site’s language or to set language-specific options in a multilingual site
• static/uploads/ for any files you want visitors to download, such as a PDF of your resume
• hugo-blox/blox/community/ install custom or community blox here
• go.mod sets the version of Hugo themes/plugins which your site uses - learn how to update

Additional Approaches

• The workflows presented here are not the only approaches to building academic websites. �
• Additional resources and approaches can be found on Stats-wiki: wiki.stat.lsa.umich.edu�
• Workshop on building academic website from previous semesters.