Merge pull request #67 from nhsuk/code-examples

Code examples

.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 library to your working files, and navigate using the components 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/component.njk

@@ -18,9 +18,10 @@
 {% endset %}
 
 {% block main %}
-  <h1 class="nhsuk-heading-xl">
-    {% if tags and "component" in tags %}<span class="nhsuk-caption-xl">Components</span>{% endif %}
+  <h1 class="nhsuk-heading-xl nhsuk-u-margin-bottom-5">
+    {% if tags and "component" in tags %}<span class="nhsuk-caption-l">Components</span>{% endif %}
     {{ title }}
   </h1>
+  <p class="nhsuk-body-l nhsuk-u-margin-bottom-7">{{ description }}</p>
   {{ content | safe }}
 {% endblock %}

docs/_includes/layouts/example.njk

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

docs/_includes/layouts/sidebar.njk

@@ -3,15 +3,15 @@
 {% block container %}
   <div class="nhsuk-width-container">
     <div class="nhsuk-grid-row">
-      <div class="nhsuk-grid-column-one-third">
+      <div class="nhsuk-grid-column-one-quarter">
         {% block sidebar_desktop %}
           <div class="app-side-navigation--desktop">
             {{ sidebar | safe }}
           </div>
         {% endblock %}
       </div>
 
-      <div class="nhsuk-grid-column-two-thirds">
+      <div class="nhsuk-grid-column-three-quarters">
         <main role="main" id="maincontent" class="nhsuk-main-wrapper">
           {% block main %}
             {{ content | safe }}

docs/assets/css/_example.scss

@@ -0,0 +1,89 @@
+/* ==========================================================================
+   #EXAMPLE
+   ========================================================================== */
+
+.app-example {
+  border: 1px solid $nhsuk-border-color;
+  padding-top: 37px; //matches height of new window link
+  margin-top: 24px;
+  position: relative;
+
+  @include mq($from: desktop) {
+    padding-top: 41px; //matches height of new window link
+  }
+}
+
+.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-bottom: 1px solid $nhsuk-border-color;
+  left: 0;
+  position: absolute;
+  padding: 8px 16px;
+  top: 0;
+  width: 100%;
+
+  a,
+  a:link,
+  a:visited {
+    color: $color_nhsuk-blue;
+    display: inline-block;
+    text-decoration: underline;
+  }
+
+  a:hover {
+    color: $nhsuk-link-hover-color;
+  }
+
+  a:focus {
+    color: $nhsuk-focus-text-color;
+    background-color: $nhsuk-focus-color;
+    text-decoration: none;
+  }
+}
+
+:not(pre) > code[class*="language-"],
+pre[class*="language-"] {
+  background: $color_nhsuk-white;
+  margin: 0;
+}
+
+.app-copy__button {
+  background-color: $color_nhsuk-white;
+  border: 1px solid $color_nhsuk-green;
+  box-shadow: 0 2px 0 $color_nhsuk-green;
+  color: $color_nhsuk-green;
+  cursor: pointer;
+  font-size: 14px;
+  padding: 2px 8px;
+  position: absolute;
+  right: 16px;
+  top: 16px;
+
+  &:hover {
+    background-color: $color_nhsuk-green;
+    color: $color_nhsuk-white;
+  }
+
+  &:focus {
+    background-color: $nhsuk-focus-color;
+    border-color: $nhsuk-focus-color;
+    box-shadow:
+      0 -2px $nhsuk-focus-color,
+      0 4px $nhsuk-focus-text-color;
+    color: $nhsuk-focus-text-color;
+  }
+}

docs/assets/css/_tabs.scss

@@ -0,0 +1,72 @@
+/* ==========================================================================
+   #TABS
+   ========================================================================== */
+
+.app-tabs {
+  margin-bottom: nhsuk-spacing(6);
+}
+
+.app-tabs__list {
+  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);
+  color: $color_nhsuk-blue;
+  display: block;
+  padding: 16px;
+  position: relative;
+  text-decoration: underline;
+
+  @include mq($from: desktop) {
+    padding: 16px 20px;
+  }
+
+  &[aria-selected="true"] {
+    background-color: $color_nhsuk-white;
+    color: $color_nhsuk-black;
+    margin-bottom: -1px;
+    padding-bottom: 21px;
+
+    &:focus {
+      background-color: $nhsuk-focus-color;
+      box-shadow:
+        0 -2px $nhsuk-focus-color,
+        inset 0 -4px $nhsuk-focus-text-color;
+    }
+  }
+}
+
+.app-tabs__panel {
+  @include nhsuk-font($size: 16);
+  background-color: $color_nhsuk-white;
+  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" %}