Within LibGuides CMS we can customize things like HTML headers and templates, CSS files, and jQuery/JavaScript code at the system, group, and guide level.
While we cannot directly use the code from this repository with LibGuides, we still want to track our changes here to have a canonical version of the customizations for our site. The code stored here and/or any generated assets must be copied and pasted into various places within LibGuides that are appropriate for the specific snippets. This README file along with other inline comments will be the source for instructions on where to add code for our customizations.
- Docs
- GitHub Actions
- CSS/SCSS
- HTML
- JavaScript
- LibCal-based Notices
- Blog Posts on the Library Home Page
docs/deploy-steps.md: the steps and commands for testing and releasing CSS, JS, and HTML changes.docs/decisions/: architecture decision records (ADRs) explaining why things work the way they do.
We are using GitHub Actions to compile CSS, HTML, and JavaScript artifacts. Automated deployment to LibGuides CMS is turned off for now. Every built file is uploaded or pasted into LibGuides by hand.
The workflow is triggered when a relevant source file is committed and pushed to this repository. It builds every file changed in the push and commits the results to the dist/ folder on the branch that was pushed. An individual file may also be rebuilt by manually running the Deploy Components workflow with the filename specified as an input parameter.
A push to main builds files with their normal names, like libguides.css. A push to any other branch builds CSS and JS files with -test names, like libguides-test.css, for checking changes on real pages before they go live. See docs/deploy-steps.md for the steps.
See ACTIONS.md for details.
The CSS for the site is written with the SCSS syntax of Sass. It cannot be directly pasted anywhere that CSS is expected. When an scss file is modified, committed, and pushed to this repository, the compiled CSS is saved in dist/: libguides.css, libcal.css, libanswers.css, or admin.css, depending on which files changed. Changes in scss/common/ rebuild all three site stylesheets.
Upload each compiled file to its own site. For LibGuides, use the “Upload Customization Files” section of the “Custom JS/CSS” tab under Admin ➜ Look & Feel. On branches other than main, the files are named with -test, like libguides-test.css.
Note: Most HTML files have a comment header which includes a Last Modified date/time that can be updated automatically with the Auto Time Stamp extension for Visual Studio Code.
HTML files keep their normal names on every branch. They change the live site as soon as they are pasted, so paste them from main's dist/ folder.
The built template files in dist/ can be pasted directly into LibGuides.
The systemwide <head> code is split across head--system-css.html and head--system-js.html. Paste the built files from dist/ into the “JS/CSS Code” field on the “Custom JS/CSS” tab under Admin ➜ Look & Feel. Custom <head> code for a specific Group is not supported.
HTML code for the header and footer sections of the site is compiled from multiple snippets in an attempt to adhere to the DRY principle.
We enter code into the systemwide header and footer sections only. Paste dist/header--system.html and dist/footer--system.html into the appropriate places in LibGuides.
Code for widgets is kept in this repository, built into dist/, and pasted into LibGuides by hand.
Name the widget code file starting with widget-- followed by a unique name and the .html extension. See widget--notices-library-4hoj8pnB.html as an example. Appending a randomly generated string to the end of the name will help ensure uniqueness.
See .github/workflows/compile.py and the conditions related to widgets.
libguides.js, libcal.js, and libanswers.js are copied into dist/ with one comment line added at the top. Upload each file from dist/ to its own site. For LibGuides, use the “Upload Customization Files” section of the “Custom JS/CSS” tab. On branches other than main, the files are named with -test, like libguides-test.js.
Run node --check on the file before uploading. A syntax error in the uploaded file fails silently on the site.
In order to display temporal alert notices on the homepage we use a LibCal calendar and transform its RSS feed into HTML fragments that are pulled onto the page via a custom JavaScript widget. We needed to use this workflow to both overcome LibGuides aggressive caching of RSS feeds and to avoid CORS issues when trying to manipulate the feed directly with JavaScript.
A LIBCAL_RSS_NOTICES_TODAY_URL repository secret is required to store the URL for the calendar day feed. The URL is typically in the form of https://libcal.caltech.edu/rss.php?cid=#️⃣&m=day where the #️⃣ symbol stands for the numeric calendar ID.
We have created both a Library notices widget and an Archives notices widget that will insert the fragments where needed. (To add these widgets in a LibGuides box, select Media / Widget, then the Reuse Existing Widget tab, and finally search for the unique widget name.)
See Widget Code for how this code is built and pasted into the site.
The library home page shows two blog posts: the featured post first, then the most recent post. With no featured post, it shows the two most recent. Only posts with the Library News subject appear.
The LibGuides blog widget cannot show a featured post, and the blog feed carries no featured marker or subjects. Instead, a scheduled GitHub Actions job in .github/workflows/blog.yml runs .github/workflows/blog.py, which reads the blog page for the featured post and subjects, and the blog feed for titles, dates, and content. It writes fragments/blog/library.html and publishes it with GitHub Pages. The Library blog widget on the home page loads that file.
To get a post on the home page, publish it without the Library News subject, then add the subject when it should appear. The next scheduled run picks it up; no code change is needed. To put a post in the first spot on the home page, also mark it as featured. A featured post without the Library News subject does not appear.