Coding Guide
Golden rule: make your code look similar to what's around it. This project touches on a lot (YAML data, SASS/CSS, JavaScript, HTML & Liquid templates, Markdown posts, etc) so it's hard to elaborate every single formatting nuance but we can always mimic what already exists.
When editing template files, pay attention to the header hierarchy. Every page should have a single <h1> and no levels should be skipped: beneath the h1 is h2, under them is h3, etc. If you want headers to display at a different size than their level, Bootstrap has handy classes like .h2. For instance, <h2 class="h4"> will be an h2 in the header hierarchy but display as the much smaller h4.
You should view all rendered pages that include the template to ensure they have a property hierarchy; you cannot necessarily assume that the fragment you're working on starts at a particular level. For instance, the HTML files under general-info/venues/ all start at <h2> because they appear together on a page https://2020.code4lib.org/general-info/venues/ with its own <h1>Venues</h1>.
In some instances, fragments are used in multiple locations where the hierarchy outside them differs, e.g. _includes/homepage/pre_conference.html is included both on the home page after an <h2> and on /schedule/timeline.html after an <h1>. We are still highlighting these problems and determining a way to address them.
If you're unfamiliar with Jekyll and its use of Liquid templates, you can read the Liquid documentation and the list of filters and tags that Jekyll provides.
When possible, use a site.data variable instead of writing out content. If a variable does not exist, consider creating one. If it's not clear where it should be created, default to our main configuration file, _data/conf.yml.
When using data, never assume that it will be filled out. At the start of the year, many variables and even data files are erased and items are unknown initially. Try to wrap sections in if statements to check that data exists.
Prefer Liquid {% comment %} blah blah blah {% endcomment %} comments over HTML <!-- blah blah --> comments because they aren't written into the HTML of the static site.
Indent four spaces whenever entering a new block-level (header, section, div, p) tag or a Liquid statement such as a loop or if condition. Feel free to indent inline-level tags if it helps with readability.
Images have alt text. Form inputs have labels. Be accessible! We run accessibility tools over our pages to catch errors.
Use Bootstrap classes frequently. Top, block-level elements of your HTML likely need some kind of Bootstrap layout class (e.g. col-xs-12, col-md-6) to handle layout across various device screen sizes.
We use SASS, an extension of CSS which is compiled down to CSS during the site's build process. While you're developing, if you run bundle exec jekyll serve it will automagically compile the SASS you write on the fly so you can keep checking the results of your changes on your local server.
Styles go in assets/_scss/ where they are be divided up by function (buttons, clip circles), segment of page (header, footer), or specific content type (testimonials, sponsors). These smaller files are then included one by one in assets/css/main.css which contains no actual styles, only SASS @import statements.
Indent two spaces. You should indent CSS properties within a selector rule, then SASS nested selectors are further indented within that.
Use variables for all colors and other values that may be repeated. Variables live in assets/_scss/_variables.scss.
Avoid ID selectors because of their specificity causes problems. In general, all CSS good advice applies. scss-lint is a good tool to check against best practices but we don't need to take it as gospel.
SASS is your friend! Use nested selectors, mixins, functions, variables to your heart's content. Most of these are powerful tools for organizing code and managing complexity/consistency.
Don't write new styles if you can use Bootstrap! We have Bootstrap 3 on the site and it provides numerous useful classes for layout and basic styling.
Code4Lib takes accessibility very seriously; there are usually multiple talks on the topic at the conference. We really want the website to live up to our community's standards. There have already been some tips in other sections but here are several general rules to keep in mind:
- content images should have
alttext; if the image is decorative, use empty alt text (e.g.alt="") - this means that a screenreader will ignore the image - iframes should have descriptive
titleattributes - foreground/background colors should have sufficient contrast, factoring in common color blindnesses
- utilize a "screenreader only" CSS class (
sr-onlyin Bootstrap) to expose otherwise hidden content to screenreaders (see the Newcomer Dinner restaurant table, for instance—visual users get a tooltip while screenreaders get the same text in aspan.sr-only) - use ARIA roles and attributes, these are particularly needed when an element does something outside its traditional HTML semantics, such as when an
ais used as a button (role=button) or a form is specifically for searching (role=search) - all form
inputs should havelabels - you should be able to navigate content using only the keyboard
There are many accessibility audit tools that aid us in identifying potential issues. The Chrome Developer Tools and WAVE are two popular, powerful ones. These will not catch every issue but are pretty great at noticing certain things, such as when the above rules are violated, color contrasts are insufficient, and header hierarchies aren't followed.
Screenshot of us passing the Chrome dev tools accessibility audit.
JS goes in /assets/js/ where there is one monolithic main.js included on every page and smaller files for specific functionality (search) or content that needs extra code (e.g. the donation thermometer).
We have jQuery available on the site. If you want to use it, it's typically good advice to put everything inside a handler that ensures the definition of the $ variable and runs on document load:
jQuery(document).ready(function($){
// do stuff here...
});We use JavaScript pretty sparingly and should try to keep it that way, or else develop better workflows around code management like we have for SASS. Lumping all our various code into one un-minified main.js is not sustainable.
As with SASS, follow common JS best practices. JSHint or similar (ESlint) is your friend. Don't make global variables.
Indent four spaces. Indent whenever entering a new block of code: if condition, loop, function, etc.
Modern ES6 JavaScript (let, const, arrow functions, new Array methods, default parameter values) is acceptable. Analytics show that our visitors use modern browsers that support ES6 and these features are also just generally widely supported by now.
You can use Jekyll site variables (e.g. let year = {{ site.data.conf.year }}) in SASS or JS files but your file must begin with two lines of three hyphens each to tell Jekyll that it needs to not treat the file as merely static and process it:
---
---
- A11y checklist
- Bootstrap (NOTE: this is for Bootstrap 3! When we update to 4 we will need to update it)
- Chrome accessibility audit
- Jekyll's Liquid template language
- SASS
- WAVE & WAVE Chrome extension