Return to all work

Hugo Static Site Development

For Cars.com, I developed a documentation website using the Hugo static site generator.

As Manager of our Design System team, I was also the sole developer working on our initiative. This meant I needed to solve for content management, organization and integration for our documentation and pattern library website. I chose Hugo as it got great reviews, had a thriving and growing support community, and builds incredibly fast.

Hugo Gulp NPM

Requirements (with my solutions):

Development considerations

  • Simple documentation site (static site using minimal JS for interactions only)
  • Easy to update (content generated from Markdown, HTML/Sass, JSON data)
  • “Live” data – specs and other data values should reflect current library values used in projects, and shouldn’t be hard-coded into the documentation (utilizes Hugo shortcodes and JSON libraries to reference CSS and other design-related values)
  • Integrate development libraries (uses a combination of NPM and Gulp to import and integrate libraries as data that can be accessed on each page)
  • Documentation site and tokens library each versioned separately
  • Visual regression testing (all patterns tested for regressions using BackstopJS)
  • Search, with type-ahead (Utilizes Algolia for instant search and type-ahead, posts and pages tagged with alternate and related terms for findability)

Content considerations

  • “Real” data tables (utilizes Hugo shortcodes and JSON data libraries to generate real data points and data tables)
  • Fully interactive patterns (patterns imported are represented with interactivity, variant switchers, inverse backgrounds, code views, and links for isolation)
  • Documented history (each pattern is comprehensive in documentation, and includes a History of Edits section explaining the whys and whos of what changed and who worked on them)
  • News and changelogs presented as separate posts with history (treated as blog/single content posts)

Working with my team, we were able to take these base technical considerations and build a fully-functioning content site. My team of traditional designers (visual and UX) was able to pick up Markdown editing techniques fairly quickly and even learned how to submit pull requests (via GitHub and BitBucket) for file edits.