How website components fit together
An overview of how website components fit together.
There are four main categories of folders: pages, includes, layouts, and data.
The _includes sub-folders are named by year and each year's folder contains multiple .html files corresponding to a discrete piece of content on the website. This includes content like the header menu, contact information at bottom of home page, the UC Love Data Week logo, etc.
The _layouts folder contains 2-3 .html files for each year. These files specify which pieces of content from that year's _includes should be included on that particular web page. For instance, the home page would likely include sponsors.html and contact.html but other pages of the website, like the calendar page, may not include those components.
The _pages folders contains the .html files that specify the pages on the UC Love Data Week website. This may be as simple as a reference to a specific layout .html file, or it may include references to content from both _layouts and _includes.
The _data folder contains sub-folders for each year. Each year's sub-folder contains .yml files specifying content for: participating campuses, campus contacts, event dates, workshop types, and workshop details.
The .yml files are arguably the most important part of the website. All other folders lay out how the website looks, functions, and fits together, but the .yml files in _data are what actually contain the content specific to the event. This is the content that populates the .html files in _includes.
Things to know about these .yml files, with examples linked from 2024 files:
- For
campuses.yml, images as specified in theimagefield should correspond to the relative path to the associated image inassets/img. Thep-campusfield specifies whether the campus will show on the front page for participating campus. - For
contacts.yml, emails have<at>instead of@. This is fine. - For
workshop_type.yml, thetype_colorfield is blank; that is fine. - For
workshops.yml- the
imgfield should be the name of the associated image fromassets/img. This does not need the relative path, just the file name of the image. - all
namefields should be unique for that year's .yml file - the
orgfield underspeakersshould match the org abbreviation as specified incampuses.yml - The fields for
description,registration-page,recording, andslideswill default to some type of 'coming soon' text if fields are left blank. Exact text is specified incalendar.htmlin the_includesfolder for that year.
- the
It is helpful to do a side-by-side comparison to familiarize with how this works in practice.
For instance, the 2023 calendar web page looks like this:
And the associated 2023 calendar.html file looks like this:
At the very top of the .html file, note the layout field. This indicates which .html file in _layouts this web page is associated with. The layout will usually be 'default', but when staging new content, having a 'placeholder' layout can be useful to test out new content and features without having it live on the main website.
Next, the permalink field is used to identify the page address off the base URL https://uc-love-data-week.github.io/. In this example, the 2023 has been archived, so the base URL is followed by the year to indicate that this is the 2023 site, and then the page name, which in this case is 'agenda'. For the current/live site pages, the permalinks will be direct to the page name (agenda, calendar, etc.); years are added to the path during the archiving process.
In the body of the file there are references to content in the associated _includes folder. This tells the webpage to include the components described in these .html files.
Tracking a piece of content through data/includes/layout/pages is useful. And mistakes happen, or rather, sometimes we're not as consistent as we could or should be. But as long as the website works, it works! In this case, the layout specified on the calendar page is '2023_default' but the layout on the landing page for 2023, as specified in _2023_pages/index.html is '2023_home'. That's why the 2023 landing page .html file looks 'clean' compared to the 2023 calendar .html file which needs to include extra content from _includes.
The includes, layout, pages, and data files are all connected and changes to one will auto-populate changes in others. Ultimately, the .yml files in _YYYY_data are the most important files. Updating the content in these .yml files will update content everywhere on the site, where that content comes from the .yml files (so: dates, workshop descriptions, campus contacts, registration links, etc.) Everything else has to do with how the web pages look, what content they contain, and what pages are publicly accessible.
The assets/img folder contains images used on the website. The home of this folder contains the UC Love Data Week logo images, campuses/ contains campus logos/branding, and workshops/ contains images associated with specific workshops. Images in workshops/ are re-used when possible (for instance, for workshops about Tableau, Python, Wikidata, etc. we have existing images we can use) and new images are added when needed.
The css folder contains css files. These mostly don't need to be updated unless there is a big change in how the website looks. The two sub-folders that are most relevant are calendar-style.css which specifies how the calendar looks (color, font, alignment, width, etc.) and search/ which contains code for the 'search' box and response formatting on the website.
The _utilities and feeds folders are related to the search functionality.
The _utilities folder contains Python code feedbuilder.py to aggregate workshop descriptions from current and prior Love Data Week events. It publishes these descriptions in a public, machine-readable feed.
The feeds folder contains output from feedbuilder.py in _utilities. The feed is available in two formats, XML and JSON. During the process of archiving the previous year, these files should be updated by running feedbuilder.py.