Assignment 9: A website to show off your work

This webpage is a walkthrough that we will follow on a class day during the semester. After that class, you will have a working personal website and a website for your team project.

PURPOSE

  • Learn how to build a website to show off your portfolio of work

  • You should update and improve the website, which will be graded for professionalism

Students with preexisting websites can use and update theirs.

GOALS

  • Use GitHub Pages to build a website a resume-style website and showcase projects, including your midterm

  • Use GitHub Pages to create a website for your final group project at the end of the semester

  • Show examples of what you can do with GitHub Pages

  • Show examples of “above and beyond” the minimal expectations for a website

WALKTHROUGH

Personal website via a template

Students with preexisting websites can use and update theirs.

To make it easier to build a website, we are going to make one using a template.

  • Go to https://github.com/donbowen/donbowen.github.io

  • Click the green [Use this template] button

  • Name it username.github.io

    • If you already have a username.github.io repo, give it any name you want (perhaps something like, “personal-website”)

      • In the resulting repo, click Settings, then Pages, then make sure the source is the main branch, then save.

  • Change the link in the about area to your username. Then go look at the website

  • Edit config (to change the left sidebar picture and links)

    • Editable sections are text in blue

  • Edit index.md (text and picture, portfolio descriptions, and links, etc)

    • Can edit directly on GitHub.com or through GitHub Desktop

  • Replace the first portfolio item on the template with your midterm report file

    • In JupyterLab, open your report file

      • Click File > “save and export as” > Markdown

      • This will generate a zip file (likely “report.zip”), extract the folder from this and upload the whole folder to your website repo.

    • In index.md, it says _**[Natural language processing 10-Ks to identify risks](midterm_summary)**_.

      • Update this to a name that fits your midterm report

      • Update the link from midterm_summary (the path to my file) with yours (“report/report” if it is inside a folder or just “report” otherwise)

      • Update the summary description

      • Update the picture by changing <img src="images/dummy_thumbnail.jpg?raw=true"/> to point at one of the pictures inside your report folder.

    • Save and commit these changes. After the website updates, refresh it

      • Check the grammar, pictures, and if the link to the report works

      • Look at the report webpage

    • Update the report.md file so it looks better. Add these lines to the top of the file:

      ---
      layout: wide_default
      ---  
      

Awesome! You have a working site! You should continue to improve it to include more things you want to show off.

  • Check that all links work

  • Improve grammar

  • Add your team project

  • Add additional portfolio items (links to reports and projects from other classes, for example)

Note on layout: The template limits you to the “Minimal” theme preset on GitHub.com. For more customizability, you can create your own GitHub Pages using other theme presets.

Getting started on a team project website

Note: If your team’s key output is a dashboard/app instead of a report, you can skip the team website.

  • Only one person on each team should do this.

    • Your work for the project will be in a different repo I set up, but your project’s website will be this one.

  • Go to https://github.com/donbowen/teamproject

  • Click the green [Use this template] button

  • Name it something related to the project

    • You can change this later, but any links to the website will need to change

  • In the resulting repo, click Settings, then Pages, then make sure the source is the main branch.

    • You can choose a different theme here if you want

  • Change the link in the code/about area to the website URL. Then go look at the website

  • Settings > Collaborators:

    • Add all teammates, and add the TA and Professor Bowen

  • In each person’s personal website, change the eventual project link to link to that website

MOVING FORWARD

A little summary of some of your options for creating websites:

Option

Pros

Cons

Default GitHub templates and Markdown files

  • Easy start
  • Can use Plotly, Altair to make interactive charts

  • Need explicit page links for interactive table of contents, navigation bar
  • Limited customization options
  • Have to “paste” output content into Markdown files
  • Have to manually convert .ipynb files into MD or HTML to post

Finding templates that you like, forking, and customizing

  • Also easy start
  • Better customization options
  • Many have already-developed interactive table of contents, navigation bar, etc. features
  • Can also use Plotly, Altair to make interactive charts

  • Have to learn template’s repo organizations
  • Need to reconfigure templates’ files to suit your own needs
  • Have to “paste” output content into Markdown files
  • Have to manually convert .ipynb files into MD or HTML to post
  • Some additional setup needed

Fastpages - https://github.com/fastai/fastpages

  • Publishes ipynb files automatically
  • Interactive visualizations work automatically

  • More overhead learning

Jupyterbooks

  • Oh la la
  • Lots of customization options
  • Best for larger projects

  • Have to learn template’s repo organizations
  • Need to reconfigure templates’ files to suit your own needs
  • Some additional setup needed