@defra/docusaurus-theme-govuk 0.0.16-alpha → 0.0.18-alpha

package/index.js

@@ -8,6 +8,61 @@ const removeMarkdown = require('remove-markdown');
 // handles deduplication automatically (second "Options" → "options-1", etc.).
 const GithubSlugger = require('github-slugger');
 
+// Remark plugin: transforms GitHub-style alert blockquotes into Docusaurus
+// containerDirective nodes so they render via the Admonition component.
+//
+//   > [!NOTE]      → :::note
+//   > [!TIP]       → :::tip
+//   > [!IMPORTANT] → :::important
+//   > [!WARNING]   → :::warning
+//   > [!CAUTION]   → :::caution
+//
+// Runs in beforeDefaultRemarkPlugins so containerDirective nodes are in place
+// before Docusaurus's admonition remark plugin processes them.
+function githubAlertToDirective(blockquote) {
+  const first = blockquote.children?.[0];
+  if (first?.type !== 'paragraph') return null;
+
+  const firstText = first.children?.[0];
+  if (firstText?.type !== 'text') return null;
+
+  const match = firstText.value.match(/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*\n?/i);
+  if (!match) return null;
+
+  const type = match[1].toLowerCase();
+  const rest = firstText.value.slice(match[0].length);
+
+  let children;
+  if (rest.trim()) {
+    children = [
+      { ...first, children: [{ ...firstText, value: rest }, ...first.children.slice(1)] },
+      ...blockquote.children.slice(1),
+    ];
+  } else if (first.children.length > 1) {
+    children = [{ ...first, children: first.children.slice(1) }, ...blockquote.children.slice(1)];
+  } else {
+    children = blockquote.children.slice(1);
+  }
+
+  return { type: 'containerDirective', name: type, attributes: {}, children };
+}
+
+function walkGithubAlerts(node) {
+  if (!Array.isArray(node.children)) return;
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (child.type === 'blockquote') {
+      const directive = githubAlertToDirective(child);
+      if (directive) { node.children[i] = directive; continue; }
+    }
+    walkGithubAlerts(child);
+  }
+}
+
+function remarkGithubAlerts() {
+  return walkGithubAlerts;
+}
+
 // Remark plugin: converts `<!-- no-sidebar -->` inline HTML comments inside
 // headings into a `data-no-sidebar` HTML attribute (via mdast hProperties) so
 // the runtime DOM scanner can detect and skip them. MDX/remark-rehype drops
@@ -102,7 +157,19 @@ function injectIntoUses(uses) {
     if (typeof use?.loader === 'string' && use.loader.includes('mdx-loader')) {
       use.options = use.options || {};
       use.options.beforeDefaultRemarkPlugins = use.options.beforeDefaultRemarkPlugins || [];
-      use.options.beforeDefaultRemarkPlugins.push(remarkNoSidebar);
+      use.options.beforeDefaultRemarkPlugins.push(remarkNoSidebar, remarkGithubAlerts);
+
+      // Add GitHub alert types not in Docusaurus's default keyword list.
+      if (use.options.admonitions !== false) {
+        const existing = use.options.admonitions || {};
+        const keywords = existing.keywords || ['note', 'tip', 'info', 'warning', 'danger'];
+        const extra = ['caution', 'important'].filter(k => !keywords.includes(k));
+        if (extra.length) {
+          use.options.admonitions = { ...existing, keywords: [...keywords, ...extra] };
+        }
+      }
+
+
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.16-alpha",
+  "version": "0.0.18-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",

package/src/css/components.scss

@@ -34,6 +34,54 @@
   min-width: 0;
 }
 
+// Admonition colour modifiers.
+// The thick left bar is drawn via ::before so it overlaps the thin border corners
+// cleanly — CSS border mitering would otherwise show a pale sliver at the joins.
+// border-left-width is kept at 5px (matching GOV.UK's original) but made transparent
+// so the element's layout is unchanged; ::before paints over that space.
+.govuk-inset-text.govuk-inset-text--note,
+.govuk-inset-text.govuk-inset-text--tip,
+.govuk-inset-text.govuk-inset-text--info,
+.govuk-inset-text.govuk-inset-text--important {
+  border: 1px solid #bad3ea;
+  border-left-width: 10px;
+  border-left-color: transparent;
+  background: none;
+  position: relative;
+
+  &::before {
+    content: '';
+    position: absolute;
+    top: -1px;
+    bottom: -1px;
+    left: -10px;
+    width: 10px;
+    background: #1d70b8;
+  }
+
+  > p:first-child strong { color: #1d70b8; }
+}
+
+.govuk-inset-text.govuk-inset-text--caution {
+  border: 1px solid #fbd6c3;
+  border-left-width: 10px;
+  border-left-color: transparent;
+  background: none;
+  position: relative;
+
+  &::before {
+    content: '';
+    position: absolute;
+    top: -1px;
+    bottom: -1px;
+    left: -10px;
+    width: 10px;
+    background: #f47738;
+  }
+
+  > p:first-child strong { color: #f47738; }
+}
+
 // Code block
 .app-code-block {
   position: relative;
@@ -56,9 +104,18 @@
   font-size: 0.875rem;
   line-height: 1.6;
   font-family: Menlo, Consolas, 'Courier New', monospace;
-  position: relative;
-  border: 1px solid #b1b4b6;
-  margin: 0;
+  background-color: #f4f8fb;
+
+  code {
+    display: block;
+
+    > div::after {
+      content: '';
+      display: inline-block;
+      width: calc(1rem + 70px);
+      line-height: 0;
+    }
+  }
 }
 
 .app-code-block__copy {
@@ -134,7 +191,7 @@
 .app-layout-sidebar__nav .not-govuk-navigation-menu__list__subitems {
 
   .not-govuk-navigation-menu__list__item {
-    padding: 5px 0 5px 15px;
+    padding: 5px 0;
     margin-bottom: 5px;
     border-left-width: 0px;
     border-left-style: solid;
@@ -145,7 +202,8 @@
 
     @media (min-width: 48.125em) {
       border-left: 4px solid #1d70b8;
-      padding-left: 10px;
+      padding-left: 11px;
+      margin-left: -15px;
       font-weight: bold;
 
       .not-govuk-navigation-menu__list__link {
@@ -162,6 +220,36 @@
   padding-left: 0;
 }
 
+// API definition list (Type, Default, etc.)
+.app-definition-list {
+  margin: 0 0 govuk-spacing(4);
+  padding: 0;
+
+  &__item {
+    display: flex;
+    gap: govuk-spacing(2);
+    align-items: baseline;
+    margin-bottom: govuk-spacing(1);
+
+    dt {
+      font-weight: 700;
+      flex-shrink: 0;
+    }
+
+    dd {
+      margin: 0;
+
+      code {
+        color: #484949;
+        font-size: 0.85em;
+        background-color: #f4f8fb;
+        padding: 1px 4px;
+        border-radius: 2px;
+      }
+    }
+  }
+}
+
 // Sidebar nav section headings and mobile toggle
 // Desktop: headings are non-link spans, visually distinct from link items
 .not-govuk-navigation-menu__list__heading {

package/src/css/prose-scope.scss

@@ -20,8 +20,29 @@
     @extend %govuk-heading-s;
   }
 
+  // Extra top padding on headings that follow a code block,
+  // matching the spacing govuk-frontend adds after paragraphs and lists
+  .app-code-block + h2:not(.app-no-prose *),
+  .app-code-block + h3:not(.app-no-prose *),
+  .app-code-block + h4:not(.app-no-prose *),
+  .app-code-block + h5:not(.app-no-prose *),
+  .app-code-block + h6:not(.app-no-prose *) {
+    padding-top: 5px;
+  }
+
+  @media (min-width: 40.0625em) {
+    .app-code-block + h2:not(.app-no-prose *),
+    .app-code-block + h3:not(.app-no-prose *),
+    .app-code-block + h4:not(.app-no-prose *),
+    .app-code-block + h5:not(.app-no-prose *),
+    .app-code-block + h6:not(.app-no-prose *) {
+      padding-top: 20px;
+    }
+  }
+
   // Body text
-  p:not(.app-no-prose *) {
+  p:not(.app-no-prose *),
+  .app-definition-list:not(.app-no-prose *) {
     @extend %govuk-body-m;
   }
 
@@ -55,5 +76,67 @@
     @extend %govuk-section-break;
     @extend %govuk-section-break--visible;
     @extend %govuk-section-break--xl;
+    border-color: #cecece;
+  }
+
+  // Inline code styling (paragraphs, list items, headings etc — but not inside pre blocks)
+  code:not(pre *):not(h1 *):not(h2 *):not(h3 *):not(h4 *):not(h5 *):not(h6 *):not(.app-no-prose *) {
+    color: #484949;
+    font-size: 0.85em;
+    background-color: #f4f8fb;
+    padding: 1px 4px;
+    border-radius: 2px;
+  }
+
+  // Lighter table borders
+  .govuk-table__header,
+  .govuk-table__cell {
+    border-bottom-color: #cecece;
+  }
+
+  // Remove the table's last row border when a section break immediately follows,
+  // so the two rules don't double up visually.
+  // Border is on td/th cells, not tr, so target those directly.
+  table:has(+ hr) tr:last-child th,
+  table:has(+ hr) tr:last-child td {
+    border-bottom: none;
+  }
+
+  // Remove bottom margin from the last paragraph inside inset and warning text
+  .govuk-inset-text,
+  .govuk-warning-text {
+    p:last-child:not(.app-no-prose *) {
+      margin-bottom: 0;
+    }
+  }
+
+  // Code block copy button
+  .app-code-block__copy {
+    font-size: 0.9rem;
+    min-width: 70px;
+    padding: 3px 10px;
+    border: 1px solid #1a65a6;
+    color: #1a65a6;
+    box-shadow: 0 2px 0 0 #1a65a6;
+    background-color: #fff;
+    text-align: center;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  
+  .app-code-block__copy:active {
+    border: 2px solid var(--govuk-focus-colour, #ffdd00);
+    padding: 2px 10px;
+    outline: 2px solid rgba(0, 0, 0, 0);
+    box-shadow: none;
+  }
+
+  .app-code-block__copy:focus:not(:hover) {
+    border: 2px solid var(--govuk-focus-colour, #ffdd00);
+    padding: 2px 10px;
+    outline: 2px solid rgba(0, 0, 0, 0);
+    color: var(--govuk-focus-text-colour, #0b0c0c);
+    background-color: var(--govuk-focus-colour, #ffdd00);
+    box-shadow: 0 2px 0 0 var(--govuk-focus-text-colour, #0b0c0c);
   }
 }

package/src/css/theme.scss

@@ -17,10 +17,38 @@
  * without this, outer chrome inherits the browser default serif.
  * GDS Transport is not bundled — Helvetica/Arial is used instead.
  */
-body {
+body,
+[class^="govuk-"],
+[class*=" govuk-"] {
   font-family: Helvetica, Arial, sans-serif;
 }
 
+/* Wider page width — overrides the 960px default from govuk-frontend.
+ * !important is needed because @not-govuk/width-container injects its CSS
+ * via the JS bundle, which loads after static stylesheets and wins the cascade.
+ *
+ * The package's margin: auto rule fires at 1020px (960 + 30 + 30), which is too
+ * early for our wider container. We restore the 30px gutters from 1020px and only
+ * allow auto-centering once the viewport is wide enough to actually cap at 1100px
+ * (1100 + 30 + 30 = 1160px). */
+.govuk-width-container {
+  max-width: 1100px !important;
+}
+
+@media (min-width: 1020px) {
+  .govuk-width-container {
+    margin-right: 30px !important;
+    margin-left: 30px !important;
+  }
+}
+
+@media (min-width: 1160px) {
+  .govuk-width-container {
+    margin-right: auto !important;
+    margin-left: auto !important;
+  }
+}
+
 /*
  * Sticky footer: Docusaurus inserts a #__docusaurus wrapper between body
  * and our layout, breaking GOV.UK Frontend's flex sticky-footer chain.

package/src/theme/Admonition/index.js

@@ -1,32 +1,27 @@
 import React from 'react';
 import {InsetText, WarningText} from '@not-govuk/simple-components';
 
-const admonitionTitles = {
-  note: 'Note',
-  tip: 'Tip',
-  info: 'Info',
-  warning: 'Warning',
-  danger: 'Danger',
-  caution: 'Caution',
+const ADMONITION_CONFIGS = {
+  note:      { label: 'Note',      modifier: 'govuk-inset-text--note'     },
+  tip:       { label: 'Tip',       modifier: 'govuk-inset-text--tip'      },
+  info:      { label: 'Info',      modifier: 'govuk-inset-text--info'     },
+  important: { label: 'Important', modifier: 'govuk-inset-text--important' },
+  caution:   { label: 'Caution',   modifier: 'govuk-inset-text--caution'  },
+  warning:   { label: 'Warning',   modifier: null },
+  danger:    { label: 'Danger',    modifier: null },
 };
 
 export default function Admonition({type = 'note', title, children}) {
-  const displayTitle = title || admonitionTitles[type] || 'Note';
+  const config = ADMONITION_CONFIGS[type] ?? ADMONITION_CONFIGS.note;
+  const displayTitle = (title || config.label).toUpperCase();
 
-  // Warning and danger types use GOV.UK WarningText
-  if (type === 'warning' || type === 'danger' || type === 'caution') {
-    return (
-      <WarningText>
-        <strong>{displayTitle}: </strong>
-        {children}
-      </WarningText>
-    );
+  if (!config.modifier) {
+    return <WarningText>{children}</WarningText>;
   }
 
-  // All other types use GOV.UK InsetText
   return (
-    <InsetText>
-      {title && <strong>{displayTitle}: </strong>}
+    <InsetText className={config.modifier}>
+      <p><strong>{displayTitle}</strong></p>
       {children}
     </InsetText>
   );

package/src/theme/CodeBlock/index.js

@@ -28,7 +28,7 @@ export default function CodeBlock({children, className: classNameProp, title}) {
         </div>
       )}
       <Highlight theme={themes.github} code={codeString} language={language}>
-        {({style, tokens, getLineProps, getTokenProps}) => (
+        {({style: {backgroundColor: _bg, ...style}, tokens, getLineProps, getTokenProps}) => (
           <pre className="app-code-block__pre" style={style}>
             <button
               type="button"

package/src/theme/MDXComponents/index.js

@@ -2,7 +2,53 @@ import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 import Heading from '@theme/Heading';
 import Admonition from '@theme/Admonition';
-import {InsetText} from '@not-govuk/simple-components';
+import {InsetText, WarningText} from '@not-govuk/simple-components';
+
+const ALERT_CONFIGS = {
+  NOTE:      { label: 'Note',      modifier: 'govuk-inset-text--note'      },
+  TIP:       { label: 'Tip',       modifier: 'govuk-inset-text--tip'       },
+  INFO:      { label: 'Info',      modifier: 'govuk-inset-text--info'      },
+  IMPORTANT: { label: 'Important', modifier: 'govuk-inset-text--important'  },
+  CAUTION:   { label: 'Caution',   modifier: 'govuk-inset-text--caution'   },
+  WARNING:   { label: 'Warning',   modifier: null }, // uses WarningText
+};
+
+const ALERT_PATTERN = /^\s*\[!(NOTE|TIP|INFO|IMPORTANT|WARNING|CAUTION)\]\s*/i;
+
+// Parses blockquote children for a GitHub-style alert marker.
+// Returns {config, allContent} if found, null otherwise.
+function parseGithubAlert(children) {
+  const childArray = React.Children.toArray(children);
+  const firstChildIndex = childArray.findIndex((c) => React.isValidElement(c));
+  const firstChild = childArray[firstChildIndex];
+  if (!firstChild?.props) return null;
+
+  const pChildren = React.Children.toArray(firstChild.props.children);
+  let mergedLeadingText = '';
+  let mergeCount = 0;
+  for (const child of pChildren) {
+    if (typeof child !== 'string') break;
+    mergedLeadingText += child;
+    mergeCount += 1;
+  }
+
+  const match = ALERT_PATTERN.exec(mergedLeadingText);
+  if (!match) return null;
+
+  const config = ALERT_CONFIGS[match[1].toUpperCase()];
+  const remainingText = mergedLeadingText.slice(match[0].length).trimStart();
+  const newPChildren = [
+    ...(remainingText ? [remainingText] : []),
+    ...pChildren.slice(mergeCount),
+  ].filter((c) => !(typeof c === 'string' && c.trim() === ''));
+
+  const contentParagraph = newPChildren.length > 0
+    ? React.cloneElement(firstChild, {key: 'content'}, ...newPChildren)
+    : null;
+  const allContent = [contentParagraph, ...childArray.slice(firstChildIndex + 1)].filter(Boolean);
+
+  return {config, allContent};
+}
 
 function GovukLink(props) {
   return <a className="govuk-link" {...props} />;
@@ -20,6 +66,61 @@ const MDXComponents = {
     }
     return <pre {...props} />;
   },
+  // Paragraphs: detect API definition patterns like **Type:** `string` and render as <dl>
+  p: ({children, ...rest}) => {
+    const childArray = React.Children.toArray(children);
+    const firstChild = childArray[0];
+
+    // A definition-list paragraph starts with a <strong> whose text ends with ':'
+    const isDefinitionTerm = (node) =>
+      React.isValidElement(node) &&
+      node.type === 'strong' &&
+      typeof node.props.children === 'string' &&
+      node.props.children.trim().endsWith(':');
+
+    if (!isDefinitionTerm(firstChild)) {
+      return <p {...rest}>{children}</p>;
+    }
+
+    // Group children into [{term, defs}] pairs split on each <strong> label
+    const items = [];
+    let current = null;
+    for (const child of childArray) {
+      if (isDefinitionTerm(child)) {
+        if (current) items.push(current);
+        current = {term: child.props.children, defs: []};
+      } else if (current) {
+        // Skip bare whitespace/newline separators between term and value
+        if (typeof child === 'string' && child.trim() === '') continue;
+        current.defs.push(child);
+      }
+    }
+    if (current) items.push(current);
+
+    // Render <dd> content, converting any **Required** (or similar flags) to (required)
+    const renderDefs = (defs) => defs.map((node) => {
+      if (
+        React.isValidElement(node) &&
+        node.type === 'strong' &&
+        typeof node.props.children === 'string'
+      ) {
+        const label = node.props.children.trim().toLowerCase();
+        return <strong key={label}> ({label})</strong>;
+      }
+      return node;
+    });
+
+    return (
+      <dl className="app-definition-list">
+        {items.map((item) => (
+          <div key={item.term} className="app-definition-list__item">
+            <dt>{item.term}</dt>
+            <dd>{renderDefs(item.defs)}</dd>
+          </div>
+        ))}
+      </dl>
+    );
+  },
   // GOV.UK table styling
   table: (props) => <table className="govuk-table" {...props} />,
   thead: (props) => <thead className="govuk-table__head" {...props} />,
@@ -27,8 +128,24 @@ const MDXComponents = {
   tr: (props) => <tr className="govuk-table__row" {...props} />,
   th: (props) => <th className="govuk-table__header" {...props} />,
   td: (props) => <td className="govuk-table__cell" {...props} />,
-  // Blockquotes rendered as GOV.UK InsetText
-  blockquote: ({children, ...rest}) => <InsetText {...rest}>{children}</InsetText>,
+  // Blockquotes rendered as GOV.UK InsetText, with support for GitHub-style alerts
+  // e.g. > [!NOTE], > [!WARNING], > [!TIP], > [!IMPORTANT], > [!CAUTION]
+  blockquote: ({children}) => {
+    const alert = parseGithubAlert(children);
+    if (!alert) return <InsetText>{children}</InsetText>;
+
+    const {config, allContent} = alert;
+    if (!config.modifier) {
+      return <WarningText>{allContent}</WarningText>;
+    }
+
+    return (
+      <InsetText className={config.modifier}>
+        <p key="title"><strong>{config.label.toUpperCase()}</strong></p>
+        {allContent}
+      </InsetText>
+    );
+  },
   h1: (props) => <Heading as="h1" {...props} />,
   h2: (props) => <Heading as="h2" {...props} />,
   h3: (props) => <Heading as="h3" {...props} />,