Skip to content

Latest commit

 

History

History
127 lines (98 loc) · 5.8 KB

CONTRIBUTING.md

File metadata and controls

127 lines (98 loc) · 5.8 KB

Contributor's Guide

First, if you're viewing this, I'd like to thank you for your interest in this project. There is only so much one brain can achieve and without the helpful input from other contributors, this site would not exist.

Contributing on this site doesn't have any particular high-barriers to entry, as it's written in vanilla HTML, CSS, and JS (using a Material framework).

Prerequisites

  • Any GNU/Linux distro
  • Python3 (ideally the latest)
  • An IDE of your choice (Atom is recommended)
  • Git
  • Bash or any other shell of your choice
  • Some basic experience with web dev
  • Some idea of Google's Material frameworks (ideally)

Getting Started

This site uses the MDC Web framework for a Material like look. Therefore in order to add something to this site, it may be useful to check out the MDC Web documentation.

The most important thing is that we are using MDC Web from the Unpkg CDN rather than installing it locally.

This is not encouraged by the MDC Team, as fetching it from the CDN means that we lose complete control over any form of customisability that provided by the SASS backend. Additionally, it also means that for every component that we try to use from the material catalog, we have to instantiate that component's required JS a bit differently than shown on the documentation.

The advantage to using the CDN is that we do not have to install NPM or any packages locally on our machine. This massively increases portability and allows anyone to just start writing content without having to worry about installing anything!

  • To get started, start by cloning the repository and firing up a web-server by doing python3 -m http.server. Then head over to 0.0.0.0:8000 and use the inspect element feature in your browser to change things. If you like those changes, use your favourite IDE to apply those changes to the appropriate part of the site.

Site Structure

As most sites do, we have a canonical index.html in the root of the repository. This is followed by three folders which provide the core of the site as well as other pages.

The Image_Assets/ directory contains the images used on the site. Inside the directory there are images used generally across all the tabs, while images for specific tabs are stored inside their own directory inside this directory.

To store the JS and CSS code we use the Site_Code/ directory. Inside this is the minified and normal versions of the code that is used by the site.

  • To generate the minfied files ready for deployment, we are using Google's trustworthy Closure Compiler on the default "Simple" optimisation setting for all JavaScript files and CSSO with settings left as is for all style-sheets.

For the rest of the pages, we use the Site_Pages/ directory. As these pages are quite simple, not containing more than basic text, we don't need to access the CSS and JS from the Site_Code/ directory, instead we opt to inline them in the actual site as they don't span many lines.

Adding content

The site is divided into 5 tabs, with each tab containing content in different cards, some of which are generated by calling JS functions, which create, initialise and insert the card into a responsive grid. If you plan on adding any cards, please note that due to the grid, you will need to add an even number of cards at a time for it to appear complete in all desktop, tablet and mobile viewports.

If you are looking to add new content or a new component, you'll need to change the lines in index.html which reference the styles.min.css and script.min.js to the non-minified ones for dev.

To add a new component, first you'll need to look at the catalog of available components, create your component and insert it into index.html in the suitable tab of your choice. Then you'll need to initialise the component using the documentation provided on the material.io website. The initialisation will usually follow this structure mdc.element.MDCElement.attachTo. To aid your purposes, you can use the pre-existing oneElementInit and initElement functions, that I've created.

For example, to add an ink-ripple effect on all mdc-list-item elements, you could do initElement('mdc-list-item', mdc.ripple.MDCRipple.attachTo) and that would initialise an ink-ripple on all list elements. To initialise an element on a single item, in this example an mdc dialog, you can use oneElementInit('query-selector', mdc.dialog.MDCDialog.attachTo). For further reference, please see the documentation.

I understand that this is a bit involved and people may not wish to pursue this work by themselves, which is absolutely fine! Just create an issue on the repo, stating your idea and I'll do my best to work with you to implement the component, given I have the required free-time.

If there are any questions regarding anything, feel free to create an issue and I'll answer them as soon as possible.

Once you've added your content/cards please ensure that you've minified the changes and inserted them into the appropriate minified files and changed all non-minified sources in the index page, before you send off your PR.

Conclusion

Once again, I would like to thank you for reading this guide and taking interest in this project. Any contribution, is absolutely welcome, although since we are typical humans, the time it takes for us to review your PRs may vary greatly depending on the time of year and the quantity of the code changed.

Have a great day!