- Stack
- Quick Start
- How to Edit
- Code Style Guide
- Styling / Sass
- Github Process
- File Structure
- Underscores vs Hyphens
- Editing Javascript
- Frameworks & Libraries
- Links / Routes
- Linter
- Where to report bugs
- Useful Resources
The website is built with the SSG Jekyll.
- Install Jekyll
- Clone this repository
- Serve the site locally with
bundle exec jekyll serve
Only invent new things if you can't use what is already there
Below is the order of how you should edit things:
- Use a component from the theme
- Use current css classes from theme
- Assemble a new component from bootstrap classes
- Create new classes, but still use bootstrap components as base
We follow Google's HTML/CSS Style Guide found here: https://google.github.io/styleguide/htmlcssguide.html
Below are highlighted guidelines:
- Protocol - Always use HTTPS for media files, stylesheets, and scripts, unless the files are not available over HTTPS
- Comments - Explain code as needed. Answer these questions
- What does it cover?
- What purpose does it serve?
- Why is respective solution used or preferred? (This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)
- Action Items - Mark todos and action items with TODO. Bonus: Create a Trello Card as well
- HTML Validity - Use tools such as the W3C HTML validator to test
Any style changes should be made with Sass. There is no need to edit any libraries such as Bootstrap because they will be updated as we update the framework.
- /base/_root.scss - Global style changes
- /base/_typography.scss - Global font styles
- /components/ - Components that are used in different pages
- /helpers/ - Animations, mixins, responsive styling
- /layout/ - Specific style changes for page layouts
- /pages/ - Styles for page-specific properties.
- /themes/ - This came with the template, no need to use this
- /vendor/ - Libraries like bootstrap
- /assets/css/main.scss - Importer for all scss files
Our Github process follows both the 1. Feature Branch Workflow and the 2. Git Centralized Workflow.
Please read the two links above before committing anything (it's a 10 minute read)
General Steps:
- Pull from master branch
- Create a new branch
- Update, add, commit and push changes
- Push feature branch to remote (master)
- Allow for feedback from teammates
- Merge your pull request
- How do I know to follow Feature Branch Workflow or Git Centralized Workflow? Timing & Feature. Timing: If the task can be completed within sitting down, not leaving the computer, and publishing the changes, then use Git Centralized Workflow. If it will take longer, use a branch. Feature: If it is a feature you are adding to the site, then it probably can't be completed as quickly as discussed above and deserves its own branch for people to review the code.
We follow a simple Jekyll file structure with layouts, includes, data, etc. All CSS, Javascript and font files are in the /assets folder. Images can be found in the /images folder.
SEO is important and it cares about how you name your images. Currently, Google wants us to name our images with hyphens. source: https://shuttermuse.com/image-seo-how-to-name-files/
TBD
Currently working out of custom.js to add additional scripts.
Library to animate elements based on scrolling. It is very lightweight and more documentation can be found here: https://github.com/michalsnik/aos
HTML/CSS/JS Framework for responsive projects - Docs
Routes file - _data/routes.yml
How it works: linkname: "/path-to-page/"
The point of this is to create a central place to hold links so that if we were to change a path to a page, we don't have to change it in all of the places it is used. This works just like any other data file.
Documentation: https://www.sitepoint.com/hacking-routing-component-jekyll/
Developer Hints for Jekyll https://devhints.io/jekyll
Trello is the best place to report bugs. Create a card with an appropriate title, link the page(s) where the problem is, [possibly] suggest a fix.
TBD