This repository is created for Purdue's CS Undergraduate Student Board website. Our main consideration is the ease of maintenance and content updates. Information that frequently changes, like members, initiatives, and Student Wiki, can all be updated through YAML and Markdown files.
This is a static site built using Jekyll, designed on Figma, and hosted here on Github Pages. Jekyll was selected due to its compatibility with GH Pages, as well as it's out-of-the-box blog functionality.
Directly editing the main branch is forbidden. To make updates, edit another branch and submit a pull request. Netlify bot will comment on your PR with a link to a deployed preview of your changes. When you merge into main a build will commence under the Actions tab.
Please take a moment to familiarize yourself with YAML and Markdown formats.
Please use an obfuscation technique to prevent web crawlers from detecting emails on our site.
Please run webp-convert
on any directories of images you add that are not in webp format.
To add a new page, create an html file in the _pages
directory. You can access it at purdueusb.com/filename
. You can use the redirect_to
and redirect_from
frontmatter attributes to add appropriate redirects or page aliases. Example:
---
title: USB Office Hours
redirect_from:
- /oh/
redirect_to: https://www.notion.so/0bb4e5da1b154b258d8bb00793117526?v=3aa761f5611f4e788d6b9855a6c20dd0
---
- Edit either
_data/members.yml
or_data/alumni.yml
with their name, title, class rank, and (optionally) an appropriate personal website. - If necessary, add their photograph in
assets/images/members
. Make sure the image file name matches their name in their yml entry, the images are square, and 300x300.- We don't want to be serving images larger than they need to be.
- Add an initiative logo in
assets/images/initiative
. Please use a square resolution, or it will be cropped to fit automatically. - Edit
_data/initiatives.yml
withtitle
,image
,description
, (optional)inactive
, (optional)buttonText
andbuttonLink
and list of participatingmembers
names (as spelled in members.yml).- An inactive entry can contain either
true | string
. True will display "INACTIVE" and anything else will be displayed as-is. - Former members can be designated alumnus by making their class a year.
- An inactive entry can contain either
- Add an objective logo to
assets/images/objectives
- Edit
_data/objectives.yml
with title, image, and description.
Wiki posts are written in Markdown only. To keep the flow of information consistent, please do not use h1 (#)
or h2 (##)
headings.
You can also use emojis seen on this cheat sheet!
A note about images: Please only use images hosted by USB - not from an outside source. In addition, use descriptive and readable captions for wiki images, as they will be displayed to the user and read aloud via screen readers.
The filename will be the URL slug, so lawson-fob.md
becomes /wiki/lawson-fob
. Be sure to include the following front matter attributes:
- title: Title of the article
- description: Describe what the article is about. Keep this down to one sentence.
- author: List of author names exactly as they appear in membership data files.
- date: Date of most recent edit
- categories: Category this fits the article, like
technical
orcampus
. Multiple categories can be included, as long as they are comma separated, an between square brackets.
Example: apply-to-usb.md
---
title: How to Apply to the USB
description: A very useful resource for prospective members.
author:
- Clippy
category:
- campus
- clubs
---
thank u for your interest
![clippy](assets/images/clippy.png)
To disable lightcase on a markdown link, use the no-lightcase
class like so:
[video link](https://youtu.be/iWowJBRMtpc?t=90s){:.no-lightcase}
This project contains submodule dependencies, so clone using git clone --recursive [email protected]:Purdue-CSUSB/purdueusb.com.git
. If you forgot to do this, run git submodule update --init --recursive
in the project root.
NPM is required (version here) to run purgecss
in production.
You can get Jekyll running by following the installation tutorial. There are instructions for Windows, macOS, and Linux. Once Jekyll is properly installed, run bundle exec jekyll serve
in the repository's root directory.
- Linux users: you can use
run.sh [-chilpt]
to run the jekyll build server conveniently.- -c) Clean jekyll cache files.
- -h) Headless mode (don't open your browser automatically).
- -i) Run
bundle install
at start. - -l) Live server (can cause gigabytes of cache buildup and require browser restart).
- -p) Production mode: runs
purgecss
(slow i know). - -t) Debug mode, shows traceback.
Note: Jekyll does not parse changes to _config.yml
in watch mode. You must restart the build server for changes to take effect.
- Make post sidebar in student resource page independent scrollable from the article content
- Decrease load time.
- Compress all image assets.
- Minify & purge css assets. Jekyll built-in compact mode is currently broken.
- Add search functionality to Student Wiki.
- Ensure proper site accessibility.
- Test with screen reader.
- Make use of ally.js or another library.
- Add USB alumni to collapsible section.
- Collect USB alumni photos, names, websites, and year they left usb
- Either create an about page (maybe about the history of the organization) or have it link to the landing instead.
- Create 404 page doodle.
- Decrease build time
- Phase out
generate.css
withtailwind.css
(closely modeled after this framework)
- Phase out
- Un-extendify sass with silent classes.
- Componentize site elements with web components
- Future deprecation issues: convert all @import statements when support is added for @use in the jekyll sass converter. See relevant issue.
- Purgecss will purge style classes used/constructed programmatically. Sometimes it is necessary to exempt classes from purgecss like so:
/*! purgecss start ignore */ .bg { @include generate-subclass($colors, 'background-color'); } /*! purgecss end ignore */
- Purgecss doesn't like to obey ignore statements ¯\_(ツ)_/¯
- Live reload can cause major cache buildup and exhaust your ram.
- An error seems to cause intermittent failure to load live changes:
ERROR Errno::ECONNRESET: Connection reset by peer @ io_fillbuf
- Build time is
s l o w
because of css class generation, while production builds are even slower to purge most of those classes. This is more or less awontfix
issue because it gives css writers major flexibility. - Don't use tab characters in
_config.yml
warning: Using the last argument as keyword parameters is deprecated
-> fix by runningbundle update jekyll
to get to4.0.1
.webp
is shamefully not supported by popular safari versions
You can access your changes from another device on your local network through your computer's local IP (e.g. 192.168.1.1:4000
).
When you make a change to the website, it's necessary to test your changes on the staging
branch before pushing to master. Once you've made a PR, netlify will automatill build and deploy a preview of the changes. You'll get a notification in the #website channel. Alternatively, you can request a build via `./build.sh [-s|-p].
If you make a change to the HTML/CSS/plugins of the site, test your changes on all screen sizes available in the devtools device toolbar. You never know what will break with CSS, so please look through the whole site to be sure it's working.
Plugins currently in use:
- Jekyll SEO tag
- Jemoji (github emoji support)
- Jekyll purgecss
- Jekyll minifier Netlify also handles minification
- jekyll-redirect-from
- jekyll-autoprefixer
Local Dependencies:
- Highlight.js: Syntax highlighting
- Lightcase: Seamlessly display image and video links in a modal dialog
- Lunr.js: Site search support
NPM Dependencies:
- Purgecss: Remove unused css classes
- Autoprefixer: Add browser-specific css attributes.
CDN Dependencies:
- Anchorjs: Provide anchor link support
- MagicGrid: Align items in a masonry grid
- FontAwesome: Vast array of vector icons
- JQuery
Here we define site configuration variables such as content collections, permalink formats, plugins, and other site-wide defaults.
Data collections can be stored in YAML files under the _data
directory, and can be accessed by using site.data.<my_collection>
in Liquid.
Refers to files within the _layouts
directory, that define the markup for your theme.
default.html
— The base layout that lays the foundation for subsequent layouts. The derived layouts inject their contents into this file at the line that says{{ content }}
and are linked to this file via FrontMatter declarationlayout: default
.wiki.html
— An extension of the base layout that includes a sidebar and content area for wiki posts.
Refers to snippets of code within the _includes
directory that can be inserted in multiple layouts (and another include-file as well) within the same theme-gem.
- Nav
footer.html
— Defines the site's footer section.header.html
— Defines the site's main header section. By default, pages defined in_data/header_links
will show up here in defined order.sidebar.html
— The sidebar of all wiki entries that is seen when a user clicks on a student resource link.
- Components
aboutus.html
— The mission and objectives of USB, and our members.initiatives.html
— Shows the cards for each initiative present in_data/initiatives.yml
.members/
— A group of components showing members of USB as listed inmembers.yml
.post.html
— The layout of a wiki resource (excludes sidebar).rating.html
— The layout of a wiki resource (excludes sidebar).social.html
— Creates a row of social media icons that are used in the footer. Clicking on these icons will take the user to our respective social media pages.
head.html
— Code-block that defines the<head></head>
in default layout.
Refers to .scss
files within the _sass
directory that define the site's styles.
theme.scss
— The core file imported by the preprocessedmain.scss
. It defines the variable defaults for the theme and also further imports sass partials to supplement itself.mixins.scss
— A file containing all miscellaneous mixins used to dynamically include styles.generate.scss
— A complex file used to generate tailwind-esque variants for html class styling, such as screen size breakpoints, or light and dark colors. Not recommended or necessary to modify this file in order to customize the theme unless you understand what you're doing.utils.scss
— Supplemental and miscellaneous styles.theme/_base.scss
— Defines base global styles for various HTML elements.theme/_layout.scss
— Defines styles specifically for layouts and layout elements.theme/_syntax-highlighting.scss
— Defines the styles for syntax-highlighting.pages/*.scss
— Each primary page may draw on a corresponding sass file for their specific files. If additional pages are added in the future, add a new.scss
file. Be sure to import this new file in themain.scss
file.
Special mention:
assets/main.scss
— The main file to be transpiled by sass into regular css. All page styles imported here on top of the theme.
Refers to various asset files within the assets
directory.
Contains the main.scss
that imports sass files from within the _sass
directory. This main.scss
is what gets processed into the theme's main stylesheet main.css
called by _layouts/default.html
via _includes/head.html
.
This directory can include sub-directories to manage assets of similar type, and will be copied over as is, to the final transformed site directory.
All assets will be compressed by the img-bot on github, so try to stick to compressable formats. Please check for quality.
You can change the default date format by specifying site.date_format
in _config.yml
.
# Date Format
# refer to https://shopify.github.io/liquid/filters/date/ to customize this
date_format: "%b %-d, %Y"
You can add links to the accounts USB maintains on other sites by adding options to the config in the following format (https://
included):
myspace: "https://myspace.com/mycoolestprofile"
Please ensure we have an svg icon for the site you add, and add one if not.
The USB serves all students, and our website is no exception. Ensuring WCAG compliance is very important, and accessibility issues have lead to lawsuits as potential violations of the ADA Title III requirement!
The WCAG is tedious to read, but first and foremost use your head and empathize with the user. Secondly, you can read a summary or checklist such as this one published in the UX Collective publication.
It doesn't have to be perfect, but we should be as compliant as possible whenever we can.