Add code examples to documentation

.eleventy.js

@@ -2,13 +2,19 @@ import path from 'path'
 import nunjucks from 'nunjucks'
 import sass from 'sass'
 import { EleventyHtmlBasePlugin } from '@11ty/eleventy'
+import syntaxHighlight from '@11ty/eleventy-plugin-syntaxhighlight'
+
+import matter from 'gray-matter'
+import fs from 'fs'
+import prettier from 'prettier'
 
 const nunjucksEnv = nunjucks.configure([
   // Our own components which we will ship in the release
   'src/components',
 
   // Includes specific to our documentation
   'docs/_includes',
+  'docs/assets',
 
   // NHS.UK frontend components
   'node_modules/nhsuk-frontend/packages/components'
@@ -20,6 +26,10 @@ export default function (eleventyConfig) {
 
   // Watch for changes in these directories and files
   eleventyConfig.addWatchTarget('./src/')
+  eleventyConfig.addWatchTarget('./docs/assets/')
+
+  // Add syntax highlighting to code blocks
+  eleventyConfig.addPlugin(syntaxHighlight)
 
   eleventyConfig.addTemplateFormats('scss')
   eleventyConfig.addExtension('scss', {
@@ -43,6 +53,32 @@ export default function (eleventyConfig) {
   // https://www.11ty.dev/docs/plugins/html-base/
   eleventyConfig.addPlugin(EleventyHtmlBasePlugin)
 
+  eleventyConfig.addShortcode('example', async function (examplePath) {
+    const exampleFile = fs
+      .readFileSync(path.join('docs/examples', examplePath), 'utf8')
+      .trim()
+    let { data, content: nunjucksCode } = matter(exampleFile)
+
+    const rawHtmlCode = nunjucksEnv.renderString(nunjucksCode)
+    const prettyHtmlCode = await prettier.format(rawHtmlCode, {
+      parser: 'html'
+    })
+
+    const href = `/examples/${examplePath.replace('.njk', '')}`
+
+    const templateData = {
+      examplePath,
+      href,
+      id: href.replace(/\//g, '-'),
+      title: data.title,
+      htmlCode: prettyHtmlCode,
+      nunjucksCode: nunjucksCode,
+      figmaLink: data.figmaLink,
+      vueLink: data.vueLink
+    }
+    return nunjucksEnv.render('example.njk', templateData)
+  })
+
   return {
     dir: {
       input: 'docs',

docs/_includes/example.njk

@@ -0,0 +1,79 @@
+<div class="app-example">
+  <span class="app-example__new-window">
+    <a href="{{ href | url }}" target="_blank">Open this example <span class="nhsuk-u-visually-hidden">({{ title }})</span> in a new window</a>
+  </span>
+  <iframe
+    onload="this.style.height = this.contentWindow.document.documentElement.scrollHeight + 'px';"
+    class="app-example__frame"
+    scrolling="auto"
+    frameborder="0"
+    height="{{ height }}"
+    src="{{ href | url }}"
+    title="{{ title }}"
+  ></iframe>
+</div>
+
+<div class="app-tabs" data-module="app-tabs">
+  <ul class="app-tabs__list" role="tablist">
+    <li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#html-default-{{ id }}" role="tab" id="tab_html-default-{{ id }}" aria-controls="html-default-{{ id }}">HTML</a></li>
+    <li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#nunjucks-default-{{ id }}" role="tab" id="tab_nunjucks-default-{{ id }}" aria-controls="nunjucks-default-{{ id }}">Nunjucks</a></li>
+    {%- if jsCode %}<li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#js-default-{{ id }}" role="tab" id="tab_js-default-{{ id }}" aria-controls="js-default-{{ id }}">JavaScript</a></li>{% endif -%}
+    {%- if figmaLink %}<li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#figma-default-{{ id }}" role="tab" id="tab_figma-default-{{ id }}" aria-controls="figma-default-{{ id }}">Figma</a></li>{% endif -%}
+    {%- if vueLink %}<li class="app-tabs__list-item" role="presentation"><a class="app-tabs__tab" href="#vue-default-{{ id }}" role="tab" id="tab_vue-default-{{ id }}" aria-controls="vue-default-{{ id }}">Vue</a></li>{% endif -%}
+  </ul>
+
+  <div class="app-tabs__panel app-tabs__panel--hidden" id="html-default-{{ id }}" role="tabpanel" aria-labelledby="tab_html-default-{{ id }}">
+    <button class="app-copy__button app-u-hidden" data-module="app-copy" data-clipboard-target="#html-default-{{ id }}-code">Copy code</button>
+    <div id="html-default-{{ id }}-code">
+      {%- highlight "html" -%}
+        {{ htmlCode | safe }}
+      {%- endhighlight -%}
+    </div>
+  </div>
+
+  <div class="app-tabs__panel app-tabs__panel--hidden" id="nunjucks-default-{{ id }}" role="tabpanel" aria-labelledby="tab_nunjucks-default-{{ id }}">
+    <button class="app-copy__button app-u-hidden" data-module="app-copy" data-clipboard-target="#nunjucks-default-{{ id }}-code">Copy code</button>
+
+    {%- if arguments -%}
+      <details class="nhsuk-details nhsuk-u-padding-3" data-module="nhsuk-details">
+        <summary class="nhsuk-details__summary">
+          <span class="nhsuk-details__summary-text">
+            Nunjucks macro options
+          </span>
+        </summary>
+        <div class="nhsuk-details__text">
+
+          {% include "./arguments/" + arguments + ".md" %}
+
+        </div>
+      </details>
+    {%- endif -%}
+
+<div id="nunjucks-default-{{ id }}-code">
+
+```jinja2
+{{ nunjucksCode | safe }}
+```
+
+</div>
+
+  </div>
+
+  {% if figmaLink -%}
+<div class="app-tabs__panel nhsuk-u-padding-2 app-tabs__panel--hidden" id="figma-default-{{ id }}" role="tabpanel" aria-labelledby="tab_figma-default-{{ id }}">
+
+  To use the component in your design, add the NHS App Figma Kit to your Figma libraries and find the component using the Assets tab.
+
+  [View component in Figma]({{ figmaLink }})
+</div>
+  {% endif -%}
+
+  {% if vueLink -%}
+<div class="app-tabs__panel nhsuk-u-padding-2 app-tabs__panel--hidden" id="vue-default-{{ id }}" role="tabpanel" aria-labelledby="tab_vue-default-{{ id }}">
+
+  To use the component in your Vue application, install the NHS App Vue Component Library and import the component.
+
+  [View component in Vue]({{ vueLink }})
+</div>
+  {% endif -%}
+</div>

docs/_includes/layouts/base.njk

@@ -10,8 +10,11 @@
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 
     <link href="/assets/css/app.css" rel="stylesheet" />
+    <script src="/assets/js/app.js" defer></script>
 
     <title>{{ title }}</title>
+
+    {% block head %}{% endblock %}
   </head>
   <body>
     {% block body %}

docs/_includes/layouts/example.njk

@@ -0,0 +1,8 @@
+{% extends "./base.njk" %}
+
+{% block header %}{% endblock %}
+{% block footer %}{% endblock %}
+
+{% block content %}
+  {{ content | safe }}
+{% endblock %}

docs/assets/css/_example.scss

@@ -0,0 +1,50 @@
+/* ==========================================================================
+   #EXAMPLE
+   ========================================================================== */
+
+.app-example {
+  background-color: $color_nhsuk-white;
+  border: 1px solid $nhsuk-border-color;
+  position: relative;
+}
+
+.app-example__frame {
+  background-color: $color_nhsuk-white;
+  border: 0;
+  display: block;
+  width: 100%;
+}
+
+.app-example-page {
+  margin-bottom: -1px;
+  padding: 30px;
+  padding-top: 60px;
+  position: relative;
+}
+
+.app-example__new-window {
+  @include nhsuk-font($size: 14);
+  border: 1px solid $nhsuk-border-color;
+  position: absolute;
+  top: -1px;
+  left: -1px;
+
+  a,
+  a:link,
+  a:visited {
+    background-color: white;
+    color: $color_nhsuk-blue;
+    display: block;
+    padding: 5px 10px;
+    text-decoration: none;
+  }
+
+  a:hover {
+    color: $nhsuk-link-hover-color;
+  }
+
+  a:focus {
+    color: $nhsuk-focus-text-color;
+    background-color: $nhsuk-focus-color;
+  }
+}

docs/assets/css/_tabs.scss

@@ -0,0 +1,67 @@
+/* ==========================================================================
+   #TABS
+   ========================================================================== */
+
+.app-tabs {
+  margin-bottom: nhsuk-spacing(6);
+}
+
+.app-tabs__list {
+  background: $color_nhsuk-white;
+  border: 1px solid $nhsuk-border-color;
+  border-top: 0;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+
+  display: flex;
+}
+
+.app-tabs__list-item {
+  border-right: 1px solid $nhsuk-border-color;
+  margin: 0;
+
+  z-index: 2;
+}
+
+.app-tabs__tab {
+  @include nhsuk-font($size: 19, $weight: bold);
+  background-color: $color_nhsuk-white;
+  color: $color_nhsuk-blue;
+  display: block;
+  padding: 20px;
+  position: relative;
+  text-decoration: none;
+
+  &[aria-selected="true"] {
+    background-color: $color_nhsuk-grey-5;
+    color: $color_nhsuk-black;
+    margin-bottom: -1px;
+    padding-bottom: 21px;
+
+    &:focus {
+      background-color: $nhsuk-focus-color;
+    }
+  }
+}
+
+.app-tabs__panel {
+  @include nhsuk-font($size: 16);
+  background-color: $color_nhsuk-grey-5;
+  border: 1px solid $nhsuk-border-color;
+  border-top: 0;
+  position: relative;
+
+  &--hidden {
+    display: none;
+  }
+
+  *:last-of-type {
+    margin-bottom: 0; // Remove margin bottom from any last element
+  }
+
+  p {
+    max-width: 100% !important;
+    padding: nhsuk-spacing(2);
+  }
+}

docs/assets/css/_utilities.scss

@@ -0,0 +1,3 @@
+.app-u-hidden {
+  display: none;
+}

docs/assets/css/app.scss

@@ -5,9 +5,15 @@
 @import "node_modules/nhsuk-frontend/packages/components/skip-link/skip-link.scss";
 @import "node_modules/nhsuk-frontend/packages/components/header/header.scss";
 @import "node_modules/nhsuk-frontend/packages/components/hero/hero.scss";
+@import "node_modules/nhsuk-frontend/packages/components/tabs/tabs.scss";
+
+@import "node_modules/prismjs/themes/prism";
 
 // Import all styles from the NHS App frontend library
 @import "src/all.scss";
 
 // Import all styles specific for the design system docs
 @import "docs/assets/css/components/side-navigation";
+@import "docs/assets/css/tabs.scss";
+@import "docs/assets/css/example.scss";
+@import "docs/assets/css/utilities.scss";

docs/assets/js/app.njk

@@ -0,0 +1,5 @@
+---
+permalink: assets/js/app.js
+---
+{% include "js/tabs.js" %}
+{% include "js/copy.js" %}

docs/assets/js/copy.js

@@ -0,0 +1,30 @@
+const Copy = function (button) {
+  this.button = button
+
+  // If the browser supports the Clipboard API, show the copy button
+  if (navigator.clipboard) {
+    this.button.classList.remove('app-u-hidden')
+  }
+
+  button.addEventListener('click', (e) => this.handleCopyClick(e))
+}
+
+Copy.prototype.handleCopyClick = function (e) {
+  e.preventDefault()
+  const copyFrom = this.button.getAttribute('data-clipboard-target')
+  const str = document.querySelector(copyFrom).innerText
+  navigator.clipboard.writeText(str)
+
+  // Change the button text to "Copied" for 5 seconds
+  const originalText = this.button.innerText
+  this.button.innerText = 'Copied'
+  setTimeout(() => {
+    this.button.innerText = originalText
+  }, 5000)
+}
+
+document
+  .querySelectorAll('[data-module="app-copy"]')
+  .forEach(function (element) {
+    new Copy(element)
+  })