spec-up-t 1.2.9 → 1.3.0

package/src/html-dom-processor.js

@@ -0,0 +1,290 @@
+'use strict';
+
+const { JSDOM } = require('jsdom');
+
+/**
+ * Sorts definition terms in HTML alphabetically (case-insensitive)
+ * 
+ * @param {string} html - The HTML content to process
+ * @returns {string} - The HTML with sorted definition terms
+ */
+function sortDefinitionTermsInHtml(html) {
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+
+  // Find the terms and definitions list
+  const dlElement = document.querySelector('.terms-and-definitions-list');
+  if (!dlElement) return html; // If not found, return the original HTML
+
+  // Collect all dt/dd pairs
+  const pairs = [];
+  let currentDt = null;
+  let currentDds = [];
+
+  // Process each child of the dl element
+  Array.from(dlElement.children).forEach(child => {
+    if (child.tagName === 'DT') {
+      // If we already have a dt, save the current pair
+      if (currentDt) {
+        pairs.push({
+          dt: currentDt,
+          dds: [...currentDds],
+          text: currentDt.textContent.trim().toLowerCase() // Use lowercase for sorting
+        });
+        currentDds = []; // Reset dds for the next dt
+      }
+      currentDt = child;
+    } else if (child.tagName === 'DD' && currentDt) {
+      currentDds.push(child);
+    }
+  });
+
+  // Add the last pair if exists
+  if (currentDt) {
+    pairs.push({
+      dt: currentDt,
+      dds: [...currentDds],
+      text: currentDt.textContent.trim().toLowerCase()
+    });
+  }
+
+  // Sort pairs case-insensitively
+  pairs.sort((a, b) => a.text.localeCompare(b.text));
+
+  // Clear the dl element
+  while (dlElement.firstChild) {
+    dlElement.removeChild(dlElement.firstChild);
+  }
+
+  // Re-append elements in sorted order
+  pairs.forEach(pair => {
+    dlElement.appendChild(pair.dt);
+    pair.dds.forEach(dd => {
+      dlElement.appendChild(dd);
+    });
+  });
+
+  // Return the modified HTML
+  return dom.serialize();
+}
+
+/**
+ * Fixes broken definition list (dl) structures in the HTML output.
+ * Specifically, it addresses the issue where transcluded terms (tref tags) break
+ * out of the definition list, creating separate lists instead of a continuous one.
+ * 
+ * The strategy:
+ * 1. Find all definition lists (dl elements) in the document
+ * 2. Use the dl with class 'terms-and-definitions-list' as the main/target list
+ * 3. Process each subsequent node after the this main dl:
+ *    - If another dl is found, merge all its children into the main dl
+ *    - If a standalone dt is found, move it and its associated dd elements into the main dl
+ *    - Remove any empty paragraphs that might be breaking the list continuity
+ * 
+ * This ensures all terms appear in one continuous definition list,
+ * regardless of how they were originally rendered in the markdown.
+ * 
+ * @param {string} html - The HTML content to fix
+ * @returns {string} - The fixed HTML content with merged definition lists
+ */
+function fixDefinitionListStructure(html) {
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+
+  // Find all dl elements first
+  const allDls = Array.from(document.querySelectorAll('dl'));
+
+  // Then filter to find the one with the terms-and-definitions-list class
+  const dlElements = allDls.filter(dl => {
+    return dl?.classList?.contains('terms-and-definitions-list');
+  });
+
+  // Find any transcluded term dt elements anywhere in the document
+  const transcludedTerms = document.querySelectorAll('dt.transcluded-xref-term');
+
+  let mainDl = null;
+
+  // If we have an existing dl with the terms-and-definitions-list class, use it
+  if (dlElements.length > 0) {
+    mainDl = dlElements[0]; // Use the first one
+  }
+  // If we have transcluded terms but no main dl, we need to create one
+  else if (transcludedTerms.length > 0) {
+    // Create a new dl element with the right class
+    mainDl = document.createElement('dl');
+    mainDl.className = 'terms-and-definitions-list';
+
+    // Look for the marker
+    const marker = document.getElementById('terminology-section-start');
+
+    if (marker) {
+      // Insert the new dl right after the marker
+      if (marker.nextSibling) {
+        marker.parentNode.insertBefore(mainDl, marker.nextSibling);
+      } else {
+        marker.parentNode.appendChild(mainDl);
+      }
+    } else {
+      // Fallback to the original approach if marker isn't found
+      const firstTerm = transcludedTerms[0];
+      const insertPoint = firstTerm.parentNode;
+      insertPoint.parentNode.insertBefore(mainDl, insertPoint);
+    }
+  }
+
+  // Safety check - if we still don't have a mainDl, exit early to avoid null reference errors
+  if (!mainDl) {
+    return html; // Return the original HTML without modifications
+  }
+
+  /**
+   * Helper function to collect dt/dd pairs from a node
+   * @param {Node} startNode - The node to start collecting from 
+   * @returns {Array} - Array of elements that are part of the definition group
+   */
+  function collectDtDdGroup(startNode) {
+    const group = [];
+    let currentNode = startNode;
+
+    // Collect the dt and all following dd elements
+    while (currentNode && (currentNode.tagName === 'DT' || currentNode.tagName === 'DD')) {
+      group.push(currentNode);
+      currentNode = currentNode.nextSibling;
+
+      // Skip text nodes (whitespace) between elements
+      while (currentNode && currentNode.nodeType === 3 && !currentNode.textContent.trim()) {
+        currentNode = currentNode.nextSibling;
+      }
+    }
+
+    return group;
+  }
+
+  // Process all transcluded terms and move them with their dd elements
+  transcludedTerms.forEach(dt => {
+    // Check if this dt is not already inside our main dl
+    if (dt.parentElement !== mainDl) {
+      // Collect the dt and its associated dd elements
+      const group = collectDtDdGroup(dt);
+
+      // Move all elements in the group to the main dl
+      group.forEach(element => {
+        if (element.parentNode) {
+          const elementClone = element.cloneNode(true);
+          mainDl.appendChild(elementClone);
+          element.parentNode.removeChild(element);
+        }
+      });
+    }
+  });
+
+  // Remove any empty dt elements that may exist
+  const emptyDts = mainDl.querySelectorAll('dt:empty');
+  emptyDts.forEach(emptyDt => {
+    emptyDt.parentNode.removeChild(emptyDt);
+  });
+
+  // Process all subsequent content after the main dl
+  let currentNode = mainDl.nextSibling;
+
+  // Process all subsequent content
+  while (currentNode) {
+    // Save the next node before potentially modifying the DOM
+    let nextNode = currentNode.nextSibling;
+
+    // Handle different node types
+    if (currentNode.nodeType === 1) { // 1 = Element node
+      if (currentNode.tagName === 'DL') {
+        // Check if this is a reference list (contains dt elements with id="ref:...")
+        const hasRefIds = currentNode.innerHTML.includes('id="ref:') ||
+          currentNode.classList.contains('reference-list');
+
+        if (!hasRefIds) {
+          // Only move non-reference definition lists - move all its children to the main dl
+          while (currentNode.firstChild) {
+            mainDl.appendChild(currentNode.firstChild);
+          }
+          // Remove the now-empty dl element
+          currentNode.parentNode.removeChild(currentNode);
+        }
+        // If it's a reference list, leave it alone
+      }
+      else if (currentNode.tagName === 'DT') {
+        // Check if this dt has a ref: id (spec reference)
+        const hasRefId = currentNode.id?.startsWith('ref:');
+
+        if (!hasRefId) {
+          // Collect the dt and its associated dd elements
+          const group = collectDtDdGroup(currentNode);
+
+          // Move all elements in the group to the main dl
+          group.forEach(element => {
+            if (element.parentNode) {
+              const elementClone = element.cloneNode(true);
+              mainDl.appendChild(elementClone);
+              element.parentNode.removeChild(element);
+            }
+          });
+
+          // Skip the nodes we just processed
+          let skipNodes = group.length - 1; // -1 because currentNode will be advanced anyway
+          while (skipNodes > 0 && nextNode) {
+            const nodeToSkip = nextNode;
+            currentNode = nextNode;
+            nextNode = nextNode.nextSibling;
+            skipNodes--;
+          }
+        }
+        // If it's a spec reference dt, leave it alone
+      }
+      else if (currentNode.tagName === 'DD') {
+        // Handle orphaned dd elements - move them to the main dl if they don't belong to a reference
+        const dtBefore = currentNode.previousSibling;
+        let hasAssociatedDt = false;
+
+        // Check if there's a dt before this dd (walking backwards through siblings)
+        let checkNode = currentNode.previousSibling;
+        while (checkNode) {
+          // Skip text nodes
+          if (checkNode.nodeType === 3 && !checkNode.textContent.trim()) {
+            checkNode = checkNode.previousSibling;
+            continue;
+          }
+
+          if (checkNode.tagName === 'DT') {
+            hasAssociatedDt = true;
+            break;
+          } else if (checkNode.tagName !== 'DD') {
+            // Found a non-dt, non-dd element, so this dd is orphaned
+            break;
+          }
+
+          checkNode = checkNode.previousSibling;
+        }
+
+        // If this dd doesn't have an associated dt in the same context, move it to main dl
+        if (!hasAssociatedDt) {
+          const ddClone = currentNode.cloneNode(true);
+          mainDl.appendChild(ddClone);
+          currentNode.parentNode.removeChild(currentNode);
+        }
+      }
+      else if (currentNode.tagName === 'P' &&
+        (!currentNode.textContent || currentNode.textContent.trim() === '')) {
+        // Remove empty paragraphs - these break the list structure
+        currentNode.parentNode.removeChild(currentNode);
+      }
+    }
+
+    // Move to the next node we saved earlier
+    currentNode = nextNode;
+  }
+
+  // Return the fixed HTML
+  return dom.serialize();
+}
+
+module.exports = {
+  sortDefinitionTermsInHtml,
+  fixDefinitionListStructure
+};

package/src/init.js

@@ -5,6 +5,9 @@ const initFlagPath = path.join(outputDir, 'init.flag');
 
 async function initialize() {
     try {
+        // Ensure the .cache directory exists
+        await fs.ensureDir(outputDir);
+        
         // Check if the init script has already run
         if (await fs.pathExists(initFlagPath)) {
             return;

package/src/install-from-boilerplate/boilerplate/.github/workflows/menu.yml

@@ -9,17 +9,16 @@ on:
         required: true
         default: 'Render specification'
         options:
-          # - Edit specification
+          - Add content
           - Render specification
-          # - Develop specification
-          - Collect external references (cached)
-          - Collect external references (no cache)
-          - Convert to PDF
+          - Export to PDF
+          - Export to DOCX
+          - Collect external references
+          - Add, remove or view xref source
+          - Configure
+          - Run health check
+          - Open documentation website
           - Freeze specification
-          # - List references
-          # - Show help
-          # - Add/remove xref source
-          # - Configure specification
           - Custom update
 
 jobs:
@@ -60,9 +59,11 @@ jobs:
           MY_PAT: ${{ secrets.MY_PAT }} # Make the secret available as an env var
         run: |
           case "${{ github.event.inputs.script }}" in
-            # "Edit specification")
-            #   node -e "require('spec-up-t')()"
-            #   ;;
+            "Add content")
+              echo "You can start adding your content to the markdown files in the 'spec' directory."
+              echo "You can do this by editing local files in an editor or by going to your repository on GitHub."
+              echo "More info: https://blockchainbird.github.io/spec-up-t-website/docs/various-roles/content-authors-guide/introduction"
+              ;;
             "Render specification")
               node --no-warnings -e "require('spec-up-t/index.js')({ nowatch: true })"
               git config --global user.email "actions@github.com"
@@ -71,31 +72,29 @@ jobs:
               git commit -m "Render specification: Update files" || echo "No changes to commit"
               git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
               ;;
-            # "Develop specification")
-            #   node -e "require('spec-up-t')({ dev: true })"
-            #   ;;
-            "Collect external references (cached)")
-              node --no-warnings -e "require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: true})"
+            # ...existing code...
+            "Export to DOCX")
+              node -e "require('spec-up-t/src/create-docx.js')"
               git config --global user.email "actions@github.com"
               git config --global user.name "GitHub Actions"
               git add .
-              git commit -m "Collect external references (cached)" || echo "No changes to commit"
+              git commit -m "Export to DOCX" || echo "No changes to commit"
               git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
               ;;
-            "Collect external references (no cache)")
-              node --no-warnings -e "require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: false, pat: process.env.MY_PAT})"
+            "Collect external references")
+              node --no-warnings -e "require('spec-up-t/src/collect-external-references.js').collectExternalReferences({ pat: process.env.MY_PAT })"
               git config --global user.email "actions@github.com"
               git config --global user.name "GitHub Actions"
               git add .
-              git commit -m "Collect external references (no cache)" || echo "No changes to commit"
+              git commit -m "Collect external references" || echo "No changes to commit"
               git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
               ;;
-            "Convert to PDF")
+            "Export to PDF")
               node -e "require('spec-up-t/src/create-pdf.js')"
               git config --global user.email "actions@github.com"
               git config --global user.name "GitHub Actions"
               git add .
-              git commit -m "Convert to PDF" || echo "No changes to commit"
+              git commit -m "Export to PDF" || echo "No changes to commit"
               git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
               ;;
             "Freeze specification")
@@ -106,18 +105,34 @@ jobs:
               git commit -m "Freeze specification" || echo "No changes to commit"
               git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
               ;;
-            # "List references")
-            #   node -e "require('spec-up-t/src/references.js')"
-            #   ;;
-            # "Show help")
-            #   cat ./node_modules/spec-up-t/src/install-from-boilerplate/help.txt || echo "Help file not found"
-            #   ;;
-            # "Add/remove xref source")
-            #   node --no-warnings -e "require('spec-up-t/src/add-remove-xref-source.js')"
-            #   ;;
-            # "Configure specification")
-            #   node --no-warnings -e "require('spec-up-t/src/configure.js')"
-            #   ;;
+            "Add, remove or view xref source")
+              node --no-warnings -e "require('spec-up-t/src/add-remove-xref-source.js')"
+              git config --global user.email "actions@github.com"
+              git config --global user.name "GitHub Actions"
+              git add .
+              git commit -m "Add, remove or view xref source" || echo "No changes to commit"
+              git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
+              ;;
+            "Configure")
+              node --no-warnings -e "require('spec-up-t/src/configure.js')"
+              git config --global user.email "actions@github.com"
+              git config --global user.name "GitHub Actions"
+              git add .
+              git commit -m "Configure" || echo "No changes to commit"
+              git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
+              ;;
+            "Run health check")
+              node --no-warnings -e "require('spec-up-t/src/health-check.js')"
+              git config --global user.email "actions@github.com"
+              git config --global user.name "GitHub Actions"
+              git add .
+              git commit -m "Run health check" || echo "No changes to commit"
+              git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
+              ;;
+            "Open documentation website")
+              echo "Opening documentation website: https://blockchainbird.github.io/spec-up-t-website/"
+              echo "Please visit the URL manually: https://blockchainbird.github.io/spec-up-t-website/"
+              ;;
             "Custom update")
               npm update && node -e "require('spec-up-t/src/install-from-boilerplate/custom-update.js')"
               git config --global user.email "actions@github.com"
@@ -133,7 +148,7 @@ jobs:
           esac
 
       - name: Deploy to GitHub Pages
-        if: success() && github.event.inputs.script != 'Show help' && github.event.inputs.script != 'Show menu'
+        if: success() && github.event.inputs.script != 'Add content' && github.event.inputs.script != 'Open documentation website' && github.event.inputs.script != 'Configure' && github.event.inputs.script != 'Run health check'
         uses: peaceiris/actions-gh-pages@v3.7.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

package/src/install-from-boilerplate/boilerplate/spec/example-markup-in-markdown.md

@@ -159,7 +159,6 @@ You can even insert content within more complex blocks, like the JSON object bel
 | ♙   | ♙   | ♙   | ♙   |     | ♙   | ♙   | ♙   |
 | ♖   | ♘   | ♗   | ♕   | ♔   |     |     | ♖   |
 
-
 ### Sequence Diagrams
 
 <pre>

package/src/install-from-boilerplate/boilerplate/spec/terms-and-definitions-intro.md

@@ -1,5 +1 @@
-# Terms and Definitions Intro
-
-## Demo terms, definitions and external definitions
-
-A demo of terms and definitions, and references to external definitions.
+[//]: # (This file, named “terms-and-definitions-intro.md” is mandatory and should not be deleted.)

package/src/install-from-boilerplate/config-scripts-keys.js

@@ -2,9 +2,9 @@ const configScriptsKeys = {
     "edit": "node -e \"require('spec-up-t')()\"",
     "render": "node --no-warnings -e \"require('spec-up-t/index.js')({ nowatch: true })\"",
     "dev": "node -e \"require('spec-up-t')({ dev: true })\"",
-    "collectExternalReferencesCache": "node --no-warnings -e \"require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: true})\"",
-    "collectExternalReferencesNoCache": "node --no-warnings -e \"require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: false})\"",
+    "collectExternalReferences": "node --no-warnings -e \"require('spec-up-t/src/collect-external-references.js').collectExternalReferences()\"",
     "topdf": "node -e \"require('spec-up-t/src/create-pdf.js')\"",
+    "todocx": "node -e \"require('spec-up-t/src/create-docx.js')\"",
     "freeze": "node -e \"require('spec-up-t/src/freeze.js')\"",
     "references": "node -e \"require('spec-up-t/src/references.js')\"",
     "help": "cat ./node_modules/spec-up-t/src/install-from-boilerplate/help.txt",
@@ -20,9 +20,9 @@ const configOverwriteScriptsKeys = {
     "edit": true,
     "render": true,
     "dev": true,
-    "collectExternalReferencesCache": true,
-    "collectExternalReferencesNoCache": true,
+    "collectExternalReferences": true,
     "topdf": true,
+    "todocx": true,
     "freeze": true,
     "references": true,
     "help": true,

package/src/install-from-boilerplate/menu.sh

@@ -6,8 +6,8 @@ function handle_choice() {
         "Add content" "do_add_content"
         "Render specification" "do_render"
         "Export to PDF" "do_topdf"
-        "Collect external references (cache, faster)" "collect_external_references_cache"
-        "Collect external references (no cache, slower)" "collect_external_references_no_cache"
+        "Export to DOCX" "do_todocx"
+        "Collect external references" "collect_external_references"
         "Add, remove or view xref source" "do_add_remove_xref_source"
         "Configure" "do_configure"
         "Run health check" "do_health_check"
@@ -47,8 +47,8 @@ function display_intro() {
    [0] Add content
    [1] Render specification
    [2] Export to PDF
-   [3] Collect external references (cache, faster)
-   [4] Collect external references (no cache, slower)
+   [3] Export to DOCX
+   [4] Collect external references
    [5] Add, remove or view xref source
    [6] Configure
    [7] Run health check
@@ -74,8 +74,8 @@ function do_add_content() {
 
 function do_render() { clear; npm run render; }
 function do_topdf() { clear; npm run topdf; }
-function collect_external_references_cache() { clear; npm run collectExternalReferencesCache; }
-function collect_external_references_no_cache() { clear; npm run collectExternalReferencesNoCache; }
+function do_todocx() { clear; npm run todocx; }
+function collect_external_references() { clear; npm run collectExternalReferences; }
 function do_add_remove_xref_source() { clear; npm run addremovexrefsource; }
 function do_configure() { clear; npm run configure; }
 function do_health_check() { clear; npm run healthCheck; }

package/src/markdown-it-extensions.js

@@ -66,12 +66,12 @@ module.exports = function (md, templates = {}) {
   md.inline.ruler.after('emphasis', 'templates', function templates_ruler(state, silent) {
     // Get the current parsing position
     var start = state.pos;
-    
+
     // Check if we're at an escaped placeholder - if so, skip processing
     if (state.src.slice(start, start + ESCAPED_PLACEHOLDER.length) === ESCAPED_PLACEHOLDER) {
       return false;
     }
-    
+
     // Check if we're at a template opening marker
     let prefix = state.src.slice(start, start + levels);
     if (prefix !== openString) return false;
@@ -203,24 +203,6 @@ module.exports = function (md, templates = {}) {
     }
   }
 
-  /**
-   * Helper function to add a 'last-dd' class to a dd token
-   * This enables special styling for the last definition description in a group
-   * 
-   * @param {Array} tokens - The token array containing the dd token
-   * @param {Number} ddIndex - The index of the dd_open token to modify
-   */
-  function addLastDdClass(tokens, ddIndex) {
-    if (ddIndex === -1) return;
-
-    const ddToken = tokens[ddIndex];
-    const classIndex = ddToken.attrIndex('class');
-    if (classIndex < 0) {
-      ddToken.attrPush(['class', 'last-dd']);
-    } else {
-      ddToken.attrs[classIndex][1] += ' last-dd';
-    }
-  }
 
   /**
    * Helper function to process definition description elements
@@ -232,23 +214,47 @@ module.exports = function (md, templates = {}) {
   function processLastDdElements(tokens, startIdx) {
     let lastDdIndex = -1; // Tracks the most recent dd_open token
 
+  }
+
+  /**
+   * Helper function to check if a definition list contains spec references
+   * Spec references have dt elements with id attributes starting with "ref:"
+   *
+   * @param {Array} tokens - The token array to search through
+   * @param {Number} startIdx - The index to start searching from (after dl_open)
+   * @return {Boolean} True if the dl contains spec references, false otherwise
+   */
+  function containsSpecReferences(tokens, startIdx) {
     for (let i = startIdx; i < tokens.length; i++) {
       if (tokens[i].type === 'dl_close') {
-        // Add class to the last <dd> before closing the entire <dl>
-        addLastDdClass(tokens, lastDdIndex);
-        break;
+        break; // Stop when we reach the end of this definition list
       }
-
-      if (tokens[i].type === 'dt_open' && !tokens[i].isEmpty) {
-        // When we find a non-empty dt, mark the previous dd as the last one in its group
-        addLastDdClass(tokens, lastDdIndex);
-        lastDdIndex = -1; // Reset for the next group
+      if (isDtRef(tokens[i])) {
+        return true;
       }
-
-      if (tokens[i].type === 'dd_open') {
-        lastDdIndex = i; // Track the most recently seen dd_open
+      if (isHtmlRef(tokens[i])) {
+        return true;
+      }
+      if (isInlineRef(tokens[i])) {
+        return true;
       }
     }
+    return false;
+  }
+
+  function isDtRef(token) {
+    if (token.type !== 'dt_open' || !token.attrs) return false;
+    return token.attrs.some(attr => attr[0] === 'id' && attr[1].startsWith('ref:'));
+  }
+
+  function isHtmlRef(token) {
+    if (token.type !== 'html_block' && token.type !== 'html_inline') return false;
+    return token.content && token.content.includes('id="ref:');
+  }
+
+  function isInlineRef(token) {
+    if (token.type !== 'inline') return false;
+    return token.content && token.content.includes('id="ref:');
   }
 
   /**
@@ -256,6 +262,10 @@ module.exports = function (md, templates = {}) {
    * Handles special styling for terminology sections and processes definition terms and descriptions
    * This function was refactored to reduce cognitive complexity by extracting helper functions
    * 
+   * IMPORTANT FIX: This function now checks if a <dl> already has a class attribute OR contains
+   * spec references (dt elements with id="ref:...") before adding the 'terms-and-definitions-list' 
+   * class. This prevents spec reference lists from being incorrectly classified as term definition lists.
+   * 
    * @param {Array} tokens - The token array being processed
    * @param {Number} idx - The index of the current token
    * @param {Object} options - Rendering options
@@ -267,8 +277,19 @@ module.exports = function (md, templates = {}) {
     const targetHtml = 'terminology-section-start';
     let targetIndex = findTargetIndex(tokens, targetHtml);
 
-    // Add class to the first <dl> only if it comes after the target HTML
-    if (targetIndex !== -1 && idx > targetIndex && !classAdded) {
+    // Check if the dl already has a class attribute (e.g., reference-list)
+    const existingClassIndex = tokens[idx].attrIndex('class');
+    const hasExistingClass = existingClassIndex >= 0;
+
+    // Check if this dl contains spec references (dt elements with id="ref:...")
+    const hasSpecReferences = containsSpecReferences(tokens, idx + 1);
+
+    // Only add terms-and-definitions-list class if:
+    // 1. It comes after the target HTML
+    // 2. We haven't added the class yet
+    // 3. The dl doesn't already have a class (to avoid overriding reference-list)
+    // 4. The dl doesn't contain spec references
+    if (targetIndex !== -1 && idx > targetIndex && !classAdded && !hasExistingClass && !hasSpecReferences) {
       tokens[idx].attrPush(['class', 'terms-and-definitions-list']);
       classAdded = true;
     }