DSSG Project Website Template

This is a template for a public gh-pages webpage for DSSG summer projects which can be freely hosted online.

Github Pages are static webpages, i.e. the content (mainly .html and .css) is sent to the user's browser and executed there (no backend server). That said, they actually can contain some interactive content which is in .javascript. The advantage is that one does not need to know these languages, all we need is to write text in markdown (thanks to numerous options of Jekyll Templates) Github Pages can be used for a lot of different scenarios:

• examples of older DSSG projects: Redistricting Project, Food Safety Project, Disaster Damage Detection Project

• example of tutorial content: git novice lesson, lesson template

• example of a personal blog: academic blog template

• example of a class website: example, template

Repo Creation

It is simpler to create a separate repo for the webpage (separate from the code) by using this template. We will also provide the option to set it up for the repo that you already have, but that will require more git work. If needed ownership and website name can be changed in the future, so pick something as a starting point.

Option 1 (new repo)

• decide on a name for the repository: we suggest to follow the format DSSGYEAR-name-of-repo (it will determine the webpage url)
• provide an eScience Data Scientist with the name and the usernames of all the team members
• we will create a repo under the uwescience organization for you and the final address will be uwescience.github.io/DSSGYEAR-name-of-repo (select uwescience/DSSG-website-template as a Repository Template)
• enable publishing through the main branch (Settings -> Pages in the left panel)
• add a link on the right for quick access to the webpage (pay attention to how the url is created)

Option 2 (existing repo)

• create a gh-pages branch (make it orphan so that it does not have any history)
• remove all tracked files from it
• pull the files from the template
• push to github the changes to create a public gh-pages branch
• enable publishing through the gh-pages branch (Settings -> Pages)

   # make an orphan branch
   git checkout --orphan gh-pages
   
   # preview files to be deleted
   git rm -rf --dry-r .
   
   # actually delete the files (double check you are on the correct branch when doing this step: it is dangerous!!!)
   git reset --hard
   
   # get the template (from template main branch to your gh-pages branch)
   git pull https://github.com/uwescience/DSSG-website-template main:gh-pages
   
   # push the local branch to a public branch on github
   git push origin gh-pages 

Configuring your website

• Modify your project name in the _config.yml file

Editing your webpage

• Each page is a markdown document

  • Markdown is a text marking language designed for the web

    • Markdown Tutorial

  • You can modify the markdown documents from the website (hit the edit button and commit when finished)

    • You can also clone the repo (or your fork of it) and make modifications locally
    • Macdown Editor for Mac
    • MarkdownPad for Windows
    • Visual Studio Code

• If you want to preview the webpage locally you need to install Jekyll(it is a bit involved), then run bundle exec jekyll serve

• You can modify your pages by setting up the sidebar:

  • https://github.com/uwescience/DSSG-website-template/blob/master/_includes/sidebar.html

• Images go into assets/img

  • they can be accessed by: <img src="{{ site.url }}{{ site.baseurl }}/assets/img/eScience.png">

  • to upload images through the website you need to have push access (otherwise do it locally and submit a pull request)

  • feel free to have a different header image relevant to your project

• Some colors and fonts are set in the .css file. You can also use the developer tools of your browser to inspect an element and modify its properties. On Chrome, right-click an element on the page and select Inspect to jump into the Elements panel. Or press Command+Option+C (Mac) or Control+Shift+C (Windows, Linux, ChromeOS).

• The theme that we are using is called Hyde: you can read more details about it below. Feel free to use a different theme (gh-pages themes, Jekyll themes), but you will have to figure out how to change it on your own. Minima is very simplistic theme which can include a blog and be adapted as you wish.

• There are some options to integrate executable notebooks with JupyterBook or Quarto. Remember that the goal of this website is to be accessible a broad audience, so the front content should not include code.

• If you do not want to rush to make your writings visible on the website, you can work in a fork, or simply work on a markdown file which you can share with your teammates for review (check out https://hackmd.io/ for collaborative markdown editing for up to 4 people)).

---

Hyde Theme Details

Hyde is a brazen two-column Jekyll theme that pairs a prominent sidebar with uncomplicated content. It's based on Poole, the Jekyll butler.

Contents

• Usage
• Options
  • Sidebar menu
  • Sticky sidebar content
  • Themes
  • Reverse layout
• Development
• Author
• License

Usage

Hyde is a theme built on top of Poole, which provides a fully furnished Jekyll setup—just download and start the Jekyll server. See the Poole usage guidelines for how to install and use Jekyll.

Options

Hyde includes some customizable options, typically applied via classes on the <body> element.

Sidebar menu

Create a list of nav links in the sidebar by assigning each Jekyll page the correct layout in the page's front-matter.

---
layout: page
title: About
---

Why require a specific layout? Jekyll will return all pages, including the atom.xml, and with an alphabetical sort order. To ensure the first link is Home, we exclude the index.html page from this list by specifying the page layout.

Sticky sidebar content

By default Hyde ships with a sidebar that affixes it's content to the bottom of the sidebar. You can optionally disable this by removing the .sidebar-sticky class from the sidebar's .container. Sidebar content will then normally flow from top to bottom.

<!-- Default sidebar -->
<div class="sidebar">
  <div class="container sidebar-sticky">
    ...
  </div>
</div>

<!-- Modified sidebar -->
<div class="sidebar">
  <div class="container">
    ...
  </div>
</div>

Themes

Hyde ships with eight optional themes based on the base16 color scheme. Apply a theme to change the color scheme (mostly applies to sidebar and links).

There are eight themes available at this time.

To use a theme, add anyone of the available theme classes to the <body> element in the default.html layout, like so:

<body class="theme-base-08">
  ...
</body>

To create your own theme, look to the Themes section of included CSS file. Copy any existing theme (they're only a few lines of CSS), rename it, and change the provided colors.

Reverse layout

Hyde's page orientation can be reversed with a single class.

<body class="layout-reverse">
  ...
</body>

Development

Hyde has two branches, but only one is used for active development.

• master for development. All pull requests should be submitted against master.
• gh-pages for our hosted site, which includes our analytics tracking code. Please avoid using this branch.

Author

Mark Otto

• https://github.com/mdo
• https://twitter.com/mdo

License

Open sourced under the MIT license.

<3