@defra/docusaurus-theme-govuk 0.0.17-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.17-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,10 +104,18 @@
   font-size: 0.875rem;
   line-height: 1.6;
   font-family: Menlo, Consolas, 'Courier New', monospace;
-  position: relative;
-  border: 1px solid #cecece;
   background-color: #f4f8fb;
-  margin: 0;
+
+  code {
+    display: block;
+
+    > div::after {
+      content: '';
+      display: inline-block;
+      width: calc(1rem + 70px);
+      line-height: 0;
+    }
+  }
 }
 
 .app-code-block__copy {

package/src/css/prose-scope.scss

@@ -22,6 +22,14 @@
 
   // 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 *),

package/src/css/theme.scss

@@ -17,7 +17,9 @@
  * 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;
 }
 

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/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} />;
@@ -84,55 +130,21 @@ const MDXComponents = {
   td: (props) => <td className="govuk-table__cell" {...props} />,
   // Blockquotes rendered as GOV.UK InsetText, with support for GitHub-style alerts
   // e.g. > [!NOTE], > [!WARNING], > [!TIP], > [!IMPORTANT], > [!CAUTION]
-  blockquote: ({children, ...rest}) => {
-    // Use \s* to tolerate any whitespace (newlines, \r\n, spaces) around the marker
-    const alertPattern = /^\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*/i;
-    const childArray = React.Children.toArray(children);
-    // Skip leading whitespace text nodes — MDX can inject them
-    const firstChildIndex = childArray.findIndex((c) => React.isValidElement(c));
-    const firstChild = childArray[firstChildIndex];
-
-    // Don't check type === 'p': when a p override is registered in MDXComponents,
-    // MDX sets the element type to the override function, not the string 'p'.
-    if (firstChild?.props) {
-      const pChildren = React.Children.toArray(firstChild.props.children);
-
-      // Remark can split "[!NOTE]" across adjacent text nodes (e.g. "[" + "!NOTE]\n...")
-      // when the paragraph also contains inline links. Merge leading text nodes before
-      // testing so the marker is always visible as a single string.
-      let mergedLeadingText = '';
-      let mergeCount = 0;
-      for (const child of pChildren) {
-        if (typeof child !== 'string') break;
-        mergedLeadingText += child;
-        mergeCount += 1;
-      }
+  blockquote: ({children}) => {
+    const alert = parseGithubAlert(children);
+    if (!alert) return <InsetText>{children}</InsetText>;
 
-      const match = alertPattern.exec(mergedLeadingText);
-      if (match) {
-        const alertType = 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;
-        // Use firstChildIndex + 1 so we don't re-include the original <p>
-        const allContent = [contentParagraph, ...childArray.slice(firstChildIndex + 1)].filter(Boolean);
-
-        return (
-          <InsetText {...rest}>
-            <p key="title"><strong>{alertType}</strong></p>
-            {allContent}
-          </InsetText>
-        );
-      }
+    const {config, allContent} = alert;
+    if (!config.modifier) {
+      return <WarningText>{allContent}</WarningText>;
     }
 
-    return <InsetText {...rest}>{children}</InsetText>;
+    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} />,