v10.0.0

Before you upgrade, please take note of any breaking changes and deprecation notices which may affect your site. View the Upgrade Guide to see examples of how to address breaking changes.

The design system has long used a custom-developed Ruby app to process and generate the documentation for web.unimelb.

Content was stored in a mixture of .slim (Ruby-specific format), .md, and .html files, which were programatically built and served locally by Ruby, and then deployed to Heroku.

At the time (circa 2014) this was an effective way of generating the documentation. The web has progressed a long way in the past 8 years and most of our team are unfamiliar with .slim files making it time-consuming to update.

For this reason the decision was made to replace the Ruby app with a node based static site generator (ssg) and convert all content and templates to standard, well-documented formats, like .html rather than .slim.

Major changes:

  • Added Eleventy static site generator #303
  • Converted all Ruby .slim documentation and layout files to .html #303
  • Converted Ruby logic to Eleventy templating where needed (ie; breadcrumbs, source code renders, conditionals) #303
  • Added Front Matter metadata to all page templates (handles titles, tags, breadcrumbs, etc.) #303
  • Added directory data to handle metadata that is common to all pages in a directory, eg; setting Components tag for all pages in components #303
  • Removed Ruby assets and dependencies once Eleventy handling all major documentation functions #303
  • Re-implemented ACE source code display/editor for components, and highlight.js code syntax highlighter for code samples #303
  • Added Mega menu to documentation site
  • Updated /layouts/ index to include missing page templates (eg; survey prompt, SSO login) which were previously orphaned #303

Summary of major new folders/files (not exhaustive):

  • /.eleventy.js - the main Eleventy config file; sets up directories, files/dirs to watch/copy, filters, plugins, etc.
  • /_site - the output directory for Eleventy generated files; the Eleventy server root
  • /_data - for Eleventy data files; currently housing mega-menu-map.json for the mega menu structure
  • /_includes - Eleventy includes files; this includes internal page layout helpers like layout-breadcrumbs.html and layout-mega-menu.html
  • /assets - Eleventy source folder for documentation; this is the same assets folder as it already existed but with all relevant documentation converted to HTML - other CSS, JS etc. remains in place
  • /assets/.eleventyignore - Eleventy will process all readable files (HTML, MD, etc.) unless configured otherwise; this tells it not to process certain files. At the moment just configured to ignore documentation files that don't start with 00
  • /assets/components - documentation for design system components (as well as all other source component files)
  • /assets/components/components.11tydata.json - directory data file for all component pages. Contains common metadata so this doesn't have to be repeated in each component file
  • /assets/layouts - site pages for documentation site, ie; homepage, getting started, components index, layouts index
  • /assets/layouts/pages - documentation for design system page layouts
  • /public - holds all the static assets that get copied to the root server folder _site on build - includes example images, documentation site-specific JS + CSS, and builds folder for uom.js and uom.css

What's removed:

  • /views - related files converted and moved to /components/layouts (for design system page templates, ie; homepage templates) or _includes/views (for internal page layouts, eg; breadcrumbs, mega menu wrappers), or removed if no longer necessary
  • Ruby-related scripts, assets, configs, dependencies

How to test

  • Run yarn to update Node packages (2 new dev dependencies - @11ty/eleventy, and @11ty/eleventy-navigation for breadcrumb functionality)
  • Run yarn build to run a normal webpack build to get the UOM js + css into the /public/builds folder for Eleventy to access
  • Run yarn start to run Eleventy build + hot-reload dev server (rebuilds on documentation file changes) - served on http://localhost:8080 by default
  • Run yarn docs:prebuild to clear out the _site directory
  • Run yarn docs:build to run a single Eleventy build

Other changes

  • Updated all references of Roboto font ➡️ Source Sans Pro #303
  • Updated README.md on how to test different versions in the CMS #308 #310
  • Updated AWS deployment instructions in README.md #316 #317
  • Integrated webpack build process with eleventy #315 #319
  • Enhanced release script #309
  • Documentation site is now hosted on Netlify allowing easier previewing of pull-requests