Recreate the Design Guide in Jekyll

[gazhands]

As a proof of concept I've (re)created the Design Guide in Jekyll. The new site is close to production-ready.

Done

• Default template features a header, footer and sidebar nav
• Styleguide sections are populated with data and templates from UI Kit
• Extra pages of content are added by creating *.md files in the repo root
• Images for the style guide live inside assets/img
• UI Kit images are loaded from https://gov-au-ui-kit.apps.staging.digital.gov.au/latest/img/*
• UI Kit javascript is loaded from https://gov-au-ui-kit.apps.staging.digital.gov.au/latest/ui-kit.min.js
• IE conditional scripts are included in the header partial
• Google Analytics is included in the header partial
• Google Fonts are loaded in the header partial
• CircleCI build

Not yet done

• Deployment
• Example pages ("layouts")
• Styleguide sections are split out individually and need to be combined in a custom template
• Home page, Getting started & Styleguide landing page content needs to be added
• Guide-specific styles (e.g. for colour swatches) need to be reapplied
• Get tags to show up in guide from KSS comments
• Git flow branches

To go live

• Review/refactor content & guide sections
• Replace all references to current guide URL https://gov-au-ui-kit.apps.staging.digital.gov.au
• Redirect all old URLs to new ones (301)

GitHub https://github.com/AusDTO/dto-design-guide

Handy links

• Liquid template reference: http://shopify.github.io/liquid/
• Jekyll & Liquid cheatsheet: https://gist.github.com/smutnyleszek/9803727
• Jekyll docs: https://jekyllrb.com/docs/home/

[klepas]

Dan W. and I are pairing on this.

[klepas]

Deployment is set up:

• develop branch: http://dto-design-guide-develop.apps.staging.digital.gov.au/
• master branch: http://dto-design-guide.apps.staging.digital.gov.au/ (not up yet since I haven’t pushed that branch yet).

[klepas]

Brendan and Dan helped me: we modified the styleguide.data gulp task to nest subsections in the JSON output.

the examples gulp task appears broken however.

[klepas]

For personal referencing: https://kss-node.github.io/kss-node/api/master/module-kss.KssStyleGuide.html

[klepas]

• Styleguide sections are split out individually and need to be combined in a custom template
• Get tags to show up in guide from KSS comments

Done!

[klepas]

• Guide-specific styles (e.g. for colour swatches) need to be reapplied

Done.

[klepas]

Git flow is implied with the branch names (I’ve been naughty so far, just working in develop straight at the moment).

(A) What’s left now

1. Example pages ("layouts") — the gulp task (examples) that builds these is broken in the UI-Kit repo at the moment and I’m unsure why. :S
2. Home page, Getting started & Styleguide landing page content needs to be added/refactored.

(B) Additional things we probably should do

1. Styleguide sections are split out individually and have their own nice custom template… but it’s not yet possible to add pages (eg accordions.md in say, _patterns/accordions.md) such that the content contained therein is intermixed with the content pulled from the uikit’s SASS source (via JSON).
2. Create a template for each tag, listing all section that contain said tag.

(C) To go live

1. Review/refactor content & guide sections.
2. Replace all references to current guide URL https://gov-au-ui-kit.apps.staging.digital.gov.au.
3. Redirect all old URLs to new ones (301).

(B) 1 needs to be addressed when we decide on the IA, but I can make headway here in the interim since we already know we want to be able to add ad-hoc pages and have them sit in the “guide”, and for those sections where we have living style guide SASS comments we want to be able to have this content automatically mixed and presented on the same page.

From a technical angle, I was thinking of using Jekyll Collections to achieve this — we’d have at least 3 collections (Foundations, Components, Patterns).

Please discuss ^

[joolswood]

@klepas are we removing the Google Analytics as discussed, until we have the privacy policy sorted?

[klepas]

@joolswood Yup, I’ve already commented it out of _config.yml.

[gazhands]

1. MVP - (4) Templates for each category
2. Example pages ("layouts") custom demo eg. grid example
3. Navigation structure L1 - horizontal navigation bar L2 - Side nav L3 Side nav (or inline links)
4. Tagging of content types in each category (components, patterns, foundations)
5. Cross linking between components><patterns

[joolswood]

Hey @klepas from what you've explained of how Jekyll Collections work it sounds like the best route.

We also need to resolve the (potential) problem of confusion arising from KSS guidance comments being presented in code block as well as md guidance.

[joolswood]

I'm hoping to be able to jump on to C1 in next sprint. Part of the issue is not being able to as yet host local builds with a working nav. I could work on it without it, but so much easier if I can prototype the content with real navigation in place.

Do you need anything else for now @klepas ?

[joolswood]

@klepas will split this work into individual issues

[klepas]

I have split the remaining items here up into:

• 404

• 426

• 423

• 427

• 424

• 425

• 429

• 428