Show Jinja Macro usage in pattern code snippets

[jmuzina]

Done

• Adds option for examples that are intended to be used as macros to be rendered as Jinja templates in example code snippets. Users have the option to switch between Jinja & HTML.
  • To show the Jinja template of an example in the documentation, add data-lang="jinja" to the placement element in the docs.
  • Refactored example Flask routes to unify their rendering logic under a single example() function. Added a route for /docs/example/<example_file_path>?raw=true that serves raw template files. This was necessary to expose the Jinja templates of examples to the front-end so they can be rendered in docs page code snippets.
• Drive-by:
  • Some improved documentation of the example.js file
  • Change all usages of var in example.js to let or const
  • Moved non-example usages of throttle() to a shared utils script
  • Changed the remote fetching protocol for example snippets from XMLHttpRequest to the more modern fetch. Extracted the remote fetching logic into its own async function, for simpler handling of multiple network requests.
  • Formatted all code sent to CodePen with js-beautify (fixes Format Codepen Code #5332)

Fixes #5254
Fixes #5332
Fixes WD-13705

QA

• Test every currently supported state of example code snippet and make sure it works as expected.
  • HTML only: Should have no language selector and display HTML. Ex: CTA Block
  • Multiple languages, built without macros: Should have language selector with an option for each language, & default to HTML. Ex: Accordion
  • Multiple languages, built with macros (that we don't want to display): Same as previous. Ex: Reduced navigation
  • HTML built with Jinja macros (that we want to display): Should default to HTML, but allow switching between Jinja & HTML. Ex: Hero 50/50
• Verify that all examples that should show macro calls have the "Jinja" option in their code snippets and default to HTML. Verify you can also switch to Jinja on those examples.
  • Hero
  • Tiered List
• Open any standalone example and verify that is uses the standalone stylesheet. For example, try button. You can verify the standalone stylesheet is used by opening the browser network tools and verifying that build.css is not loaded on a hard-refresh.
• Find an example that uses multiple languages (such as reduced navigation) and open the example in CodePen. Verify that all languages are populated in CodePen, and all languages are indent-formatted.

Check if PR is ready for release

If this PR contains Vanilla SCSS code changes, it should contain the following changes to make sure it's ready for the release:

• PR should have one of the following labels to automatically categorise it in release notes:
  • Feature 🎁, Breaking Change 💣, Bug 🐛, Documentation 📝, Maintenance 🔨.
• Vanilla version in package.json should be updated relative to the most recent release, following semver convention:
  • if CSS class names are not changed it can be bugfix release (x.x.X)
  • if CSS class names are changed/added/removed it should be minor version (x.X.0)
  • see the wiki for more details
• Any changes to component class names (new patterns, variants, removed or added features) should be listed on the what's new page.

Screenshots

[webteam-app]

Demo

Jenkins

demos.haus

[jmuzina]

Added the base behavior of showing both Jinja and HTML in the docs. This needs to be accompanied by the following:

• Documentation of how to import/install the macros (should this be a separate PR?) @pastelcyborg
• Explanation of the macro parameters and usage for each example that uses the macros.

FYI @pastelcyborg @advl

[jmuzina]

Updated this to syntax-highlight the HTML within macro slots, as I noticed they weren't highlighted in #5331

[pastelcyborg]

I'm not sure I'd default to showing Jinja for the examples with macros - I think HTML is always the best default. We should probably assume our default user is external and would get limited value out of the macros.

[jmuzina]

I'm not sure I'd default to showing Jinja for the examples with macros - I think HTML is always the best default. We should probably assume our default user is external and would get limited value out of the macros.

Good call, switched so HTML is the default rather than Jinja