I. Why is Personal Website needed?

Personal website is a professional representation of your academic and career records. It provides a home for hosting research, work and academic updates. It needs be:

  • Current (delayed revision for over three months means your negligence)
  • Open, sharing research findings and open-source materials (e.g. software, writing) to contribute to the community
  • Friendly

II. What it takes to create a personal website?

Three steps in creating a personal website:

  1. Design and configuration of the website
  2. Editing content files
  3. Posting/uploading files to host (deployment)

For the first steps, professional web designers create themes and templates for different styles. Academicians primarily select simple and functional designs. This workshop will not cover too much about the design but more on the file editing and deployment.

III. Methods of Personal website creation and hosting on GitHub

There are many ways of creating and hosting websites. Most services are not free or free with advertisements. It is your personal decision to pay $20-$50 a month to build and maintain a website. This workshop offers easy and free methods to do the same, but on GitHub. Paying or not, it is still the owner’s responsibility to update and maintain the website. The advantage of GitHub hosting is free and reliable. The disadvantage is the content is opening public. In other words, this website is to present your professional public profile. For private materials, you can either pay for a private GitHub account or choose other commercial services.

1. Using GitHub Pages

This is the easiest way to create a website with the domain name https://username.github.io/repositoryname.

  1. Be sure you create your username right

    1. username is your GitHub account name

    2. To be professional, avoid using fancy, cartoon or movie character names

  2. Repository name should be meaningful (e.g. project name)

  3. Theme choices are limited but you may advance to Jekyll for more choices

To start,

  1. Create a new repository

    1. Use ‘username.github.io’ as the repository name. This will be your default website domain, which is username.github.io (e.g. johndoe.github.io, karlho.github.io)
  2. Enter that repository, click settings on the top menu bar.

  3. On the left sidebar, click Pages.

  4. Select a theme

  5. Once created, your website files are located in the gh-pages branch. Make sure you enter this branch to edit the content. By default, the main branch is shown when entering the repository.

In a nutshell,

Create repository —> Settings —> Pages —> Select Theme —> Website is ready

You may edit the _config.yml (pronounced yam’o) file and change the header information:

theme: jekyll-theme-minimal
title: John Doe
description: Bookmark this to keep an eye on my project updates!

Edit the index.md and add content using Markdown, which is basically plain text with simple tags as follows:

# Header 1
## Header 2
### Header 3

- Bulleted
- List

1. Numbered
2. List

**Bold** and _Italic_ and `Code` text

[Link](url)  
![Image](src)

2. RStudio (Quarto)

Example

Quarto is an open-source scientific and technical publishing system built on a document converter called Pandoc. It is multilingual (R, Python, Julia and Observable) and can be used for creating a wide variety of documents using simple plain text markdown (e.g. R Markdown). Examples include website (static), academic reports, presentations, blogs. It can accommodate LaTeX for scientific equations and more advanced features such as blogs and conversion to pdf, html and MS Word.

  1. Creation of website files

  2. Create a New Project (top right Project link in RStudio)

  3. Choose New Directory and Quarto Website

  4. Give the name of directory “username.github.io” with your GitHub username (e.g. karlho.github.io)

  5. Editing website files using Quarto

First edit the _quarto.yml then other qmd files, which are Markdown files.

The _quarto.yml controls the style of the website:

project:
  type: website

website:
  title: "karlho.github.io"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

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

editor: visual

In the website section, rename the title to your name (e.g. Karl Ho). The navbar controls the top navigation bar starting from the left. You can add other pages such as research, personal, etc.

The format part control document output. In this case, it exports into html with the choice of theme, which is from Bootstrap 3. The cosmo theme is used here but choose your favorite theme from the Bootstrap website (e.g. united, sandpaper).

Then, the index.qmd file. This file is the front page (will be converted to index.html), so it is recommended to use this to introduce yourself or the latest developments (e.g. presentations, projects, etc.). You can replace with the following sample text:

---
title: "John Doe"
---

I am a doctoral student studying the political economy of East Asia and US.  My research topic is on rent-seeking behaviors in last two decades

### More Information

Interests:

  * Data Science 
  * Time series modeling

### Contact me

[johndoe@utdallas.edu](mailto:johndoe@utdallas.edu)

[Website](https://johndoe.github.io)  

The rest will be just edit the pages (qmd) you want to post on your website (i.e. research.qmd, teach.qmd, etc)


---
title: "About"
---

More about this website.

Once all files are ready, use the Build website button (under Build tab in Environment window on top right of RStudio). The rendering process converts the .qmd files into html files under the _site folder.

Now your website is ready locally. You can check the links and make sure they all work and that related files (e.g. CV) are in the same _site folder. The next part is to deploy to your host, which is GitHub.

  1. Uploading to GitHub (deployment)

Once all website related files are ready, you can upload all files to a specific repository (username.github.io). If you have created previously a GitHub Pages website, it is recommended you delete that repository and create a blank, new one with the same name. You can create a Readme.md file for the empty repository.

Once the empty repository is created, click on Add file –> upload files to bring all your website files to that repository. Alternatively, you can drag and drop all files in the _site folder including the subdirectory/subfolder (i.e. site_libs).

One last step is to remove the Readme.md (since it is the first file to be read for website). Then the index.html will be come the homepage file a.k.a. your own website now.

3. Jekyll Now

Example

This method allows another minimalist approach in creating a clean, simple but more flexible website. Barry Clark’s Jekyll Now makes it very simple: just clone and start editing. His GitHub page gives detailed description step by step. The following steps are basically adapted from his instructions:

  1. Fork Jekyll Now to your User Repository

    1. Rename the repository to username.github.io

    2. If you have created a repository in that name already (e.g. you created one using GitHub Pages), you may delete the old one before renaming it.

  2. Customize the _config.yaml with your person information such as name, social media account, etc.

    1. You can also add and edit content files such as about.md, research.md, etc.

    2. Be sure you edit the navigation link names in the /_layouts/default.html. Some simple HTML editing is needed. For example, locate the navadd links in the header section using the following:

    <nav>
    <a href=“{{ site.baseurl }}/research”>Research</a>
    <a href=“{{ site.baseurl }}/teaching”>Teaching</a>
    <a href=“{{ site.baseurl }}/KarlHocv.pdf”>CV</a>
    <a href=“{{ site.baseurl }}/”>Blog</a>
    <a href=“{{ site.baseurl }}/about”>About</a>
    </nav>
  3. Start editing contents as post (blog)

    1. Create md files in the /posts/ subdirectory and name the file by date (e.g. 2014-3-3-Hello-World.md). The post will appear on homepage with hyperlink Hello-World and point to the post/blog page.

The author Barry Clark writes an article to give detailed step-by-step instructions.

For more detailed information about Jekyll, click here to home GitHub site which provides more information such as additional themes and editing tips.

IV. More advanced options

Example

Like Jekyll, Hugo is another static site generator which allows more themes designs. karlho.com is created using a theme called academic kickstart (now called wowchemy). Netlify provides free hosting of websites on GitHub. If you prefer, you can purchase a dedicated domain such as johndoe.com and have Netlify host it with contents on GitHub. Domain prices vary from $10 to $70 a year.

Example (UTD)

UTD has a personal website service. The advantage is your domain is under UTD (e.g. https://www.utdallas.edu/~pea), making your profile officially affiliated with the university. Since you have created a website using RStudio, you can upload the content files to the UTD server. There are several notes to be taken for creating UTD website:

  1. Uploading requires SSH and DUO two factor authentication. If you have installed the latter on your phone, you can authenticate every upload/operation one at a time.
  2. Once the files are uploaded, be sure to check the permission to be 755 (Read and execute by others).