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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.16-alpha",
+  "version": "0.0.17-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

@@ -57,7 +57,8 @@
   line-height: 1.6;
   font-family: Menlo, Consolas, 'Courier New', monospace;
   position: relative;
-  border: 1px solid #b1b4b6;
+  border: 1px solid #cecece;
+  background-color: #f4f8fb;
   margin: 0;
 }
 
@@ -134,7 +135,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 +146,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 +164,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,21 @@
     @extend %govuk-heading-s;
   }
 
+  // Extra top padding on headings that follow a code block,
+  // matching the spacing govuk-frontend adds after paragraphs and lists
+  @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 +68,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

@@ -21,6 +21,32 @@ body {
   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/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

@@ -20,6 +20,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 +82,58 @@ 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, ...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;
+      }
+
+      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>
+        );
+      }
+    }
+
+    return <InsetText {...rest}>{children}</InsetText>;
+  },
   h1: (props) => <Heading as="h1" {...props} />,
   h2: (props) => <Heading as="h2" {...props} />,
   h3: (props) => <Heading as="h3" {...props} />,