spec-up-t 1.1.55 → 1.2.1

package/index.js

@@ -1,4 +1,5 @@
 const { initialize } = require('./src/init');
+const {fetchExternalTerms} = require('./src/utils/fetch');
 
 module.exports = async function (options = {}) {
   try {
@@ -30,6 +31,8 @@ module.exports = async function (options = {}) {
     const modulePath = findPkgDir(__dirname);
     let config = fs.readJsonSync('./output/specs-generated.json');
 
+    const externalTerms = fetchExternalTerms();
+
     const createExternalSpecsList = require('./src/create-external-specs-list.js');
 
     const externalSpecsList = createExternalSpecsList(config);
@@ -46,6 +49,134 @@ module.exports = async function (options = {}) {
     let externalReferences;
     let references = [];
     let definitions = [];
+    var toc;
+    var specGroups = {};
+    var noticeTitles = {};
+
+    const noticeTypes = {
+      note: 1,
+      issue: 1,
+      example: 1,
+      warning: 1,
+      todo: 1
+    };
+    const spaceRegex = /\s+/g;
+    const specNameRegex = /^spec$|^spec[-]*\w+$/i;
+    const terminologyRegex = /^def$|^ref$|^xref|^tref$/i;
+    const specCorpus = fs.readJsonSync(modulePath + '/assets/compiled/refs.json');
+    const containers = require('markdown-it-container');
+
+    /* 
+    `const md` is assigned an instance of the markdown-it parser configured with various plugins and extensions. This instance (md) is intended to be used later to parse and render Markdown strings.
+    
+    The md function (which is an instance of the markdown-it parser) takes a Markdown string as its primary argument. It is called elsewhere as follows: `md.render(doc)`
+    */
+    const md = require('markdown-it')({
+      html: true,
+      linkify: true,
+      typographer: true
+    })
+      .use(require('./src/markdown-it-extensions.js'), [
+        {
+          filter: type => type.match(terminologyRegex),
+          parse(token, type, primary) {
+            if (!primary) return;
+            if (type === 'def') {
+              definitions.push(token.info.args);
+              return token.info.args.reduce((acc, syn) => {
+                return `<span id="term:${syn.replace(spaceRegex, '-').toLowerCase()}">${acc}</span>`;
+              }, primary);
+            }
+            else if (type === 'xref') {
+              // Get the URL for the external specification reference, or default to '#' if not found
+              const externalSpec = findExternalSpecByKey(config, token.info.args[0]);
+              const url = externalSpec?.gh_page || '#';
+
+              const term = token.info.args[1].replace(spaceRegex, '-').toLowerCase();
+              return `<a class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}"
+              href="${url}#term:${term}">${token.info.args[1]}</a>`;
+            }
+            else if (type === 'tref') {
+              return `<span class="transcluded-xref-term" id="term:${token.info.args[1]}">${token.info.args[1]}</span>`;
+            }
+            else {
+              references.push(primary);
+              return `<a class="term-reference" href="#term:${primary.replace(spaceRegex, '-').toLowerCase()}">${primary}</a>`;
+            }
+          }
+        },
+        {
+          filter: type => type.match(specNameRegex),
+          parse(token, type, name) {
+            if (name) {
+              let _name = name.replace(spaceRegex, '-').toUpperCase();
+              let spec = specCorpus[_name] ||
+                specCorpus[_name.toLowerCase()] ||
+                specCorpus[name.toLowerCase()] ||
+                specCorpus[name];
+              if (spec) {
+                spec._name = _name;
+                let group = specGroups[type] = specGroups[type] || {};
+                token.info.spec = group[_name] = spec;
+              }
+            }
+          },
+          render(token, type, name) {
+            if (name) {
+              let spec = token.info.spec;
+              if (spec) return `[<a class="spec-reference" href="#ref:${spec._name}">${spec._name}</a>]`;
+            }
+            else return renderRefGroup(type);
+          }
+        }
+      ])
+      .use(require('markdown-it-attrs'))
+      .use(require('markdown-it-chart').default)
+      .use(require('markdown-it-deflist'))
+      .use(require('markdown-it-references'))
+      .use(require('markdown-it-icons').default, 'font-awesome')
+      .use(require('markdown-it-ins'))
+      .use(require('markdown-it-mark'))
+      .use(require('markdown-it-textual-uml'))
+      .use(require('markdown-it-sub'))
+      .use(require('markdown-it-sup'))
+      .use(require('markdown-it-task-lists'))
+      .use(require('markdown-it-multimd-table'), {
+        multiline: true,
+        rowspan: true,
+        headerless: true
+      })
+      .use(containers, 'notice', {
+        validate: function (params) {
+          let matches = params.match(/(\w+)\s?(.*)?/);
+          return matches && noticeTypes[matches[1]];
+        },
+        render: function (tokens, idx) {
+          let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/);
+          if (matches && tokens[idx].nesting === 1) {
+            let id;
+            let type = matches[1];
+            if (matches[2]) {
+              id = matches[2].trim().replace(/\s+/g, '-').toLowerCase();
+              if (noticeTitles[id]) id += '-' + noticeTitles[id]++;
+              else noticeTitles[id] = 1;
+            }
+            else id = type + '-' + noticeTypes[type]++;
+            return `<div id="${id}" class="notice ${type}"><a class="notice-link" href="#${id}">${type.toUpperCase()}</a>`;
+          }
+          else return '</div>\n';
+        }
+      })
+      .use(require('markdown-it-prism'))
+      .use(require('markdown-it-toc-and-anchor').default, {
+        tocClassName: 'toc',
+        tocFirstLevel: 2,
+        tocLastLevel: 4,
+        tocCallback: (_md, _tokens, html) => toc = html,
+        anchorLinkSymbol: '#', // was: §
+        anchorClassName: 'toc-anchor d-print-none'
+      })
+      .use(require('@traptitech/markdown-it-katex'))
 
     const katexRules = ['math_block', 'math_inline'];
     const replacerRegex = /\[\[\s*([^\s\[\]:]+):?\s*([^\]\n]+)?\]\]/img;
@@ -58,10 +189,34 @@ module.exports = async function (options = {}) {
           return fs.readFileSync(path, 'utf8');
         }
       },
+      {
+        test: 'spec',
+        transform: function (originalMatch, type, name) {
+          // Simply return an empty string or special marker that won't be treated as a definition term
+          // The actual rendering will be handled by the markdown-it extension
+          return `<span class="spec-marker" data-spec="${name}"></span>`;
+        }
+      },
+      /**
+       * Custom replacer for tref tags that converts them directly to HTML definition term elements.
+       * 
+       * This is a critical part of our solution for fixing transcluded terms in definition lists.
+       * When a [[tref:spec,term]] tag is found in the markdown, this replacer transforms it into
+       * a proper <dt> element with the appropriate structure before the markdown parser processes it.
+       * 
+       * By directly generating the HTML structure (instead of letting the markdown-it parser
+       * handle it later), we prevent the issue where transcluded terms break the definition list.
+       * 
+       * @param {string} originalMatch - The original [[tref:spec,term]] tag found in the markdown
+       * @param {string} type - The tag type ('tref')
+       * @param {string} spec - The specification identifier (e.g., 'wot-1')
+       * @param {string} term - The term to transclude (e.g., 'DAR')
+       * @returns {string} - HTML representation of the term as a dt element
+       */
       {
         test: 'tref',
         transform: function (originalMatch, type, spec, term) {
-          return `${originalMatch}\n: <span class="placeholder-tref">No custom content found for ${spec}:${term}</span> { .placeholder-dd }\n`;
+          return `<dt class="transcluded-xref-term"><span class="transcluded-xref-term" id="term:${term.replace(/\s+/g, '-').toLowerCase()}">${term}</span></dt>`;
         }
       }
     ];
@@ -85,6 +240,19 @@ module.exports = async function (options = {}) {
 
     const xtrefsData = createScriptElementWithXTrefDataForEmbeddingInHtml();
 
+    /**
+     * Processes custom tag patterns in markdown content and applies transformation functions.
+     * 
+     * This function scans the document for special tag patterns like [[tref:spec,term]]
+     * and replaces them with the appropriate HTML using the matching replacer.
+     * 
+     * For tref tags, this is where the magic happens - we intercept them before
+     * the markdown parser even sees them, and convert them directly to HTML structure
+     * that will integrate properly with definition lists.
+     * 
+     * @param {string} doc - The markdown document to process
+     * @returns {string} - The processed document with tags replaced by their HTML equivalents
+     */
     function applyReplacers(doc) {
       return doc.replace(replacerRegex, function (match, type, args) {
         let replacer = replacers.find(r => type.trim().match(r.test));
@@ -95,6 +263,7 @@ module.exports = async function (options = {}) {
         return match;
       });
     }
+
     function normalizePath(path) {
       return path.trim().replace(/\/$/g, '') + '/';
     }
@@ -137,212 +306,282 @@ module.exports = async function (options = {}) {
       throw Error("katex distribution could not be located");
     }
 
-    try {
+    function sortDefinitionTermsInHtml(html) {
+      const { JSDOM } = require('jsdom');
+      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);
+        }
+      });
 
-      var toc;
-      var specGroups = {};
-      const noticeTypes = {
-        note: 1,
-        issue: 1,
-        example: 1,
-        warning: 1,
-        todo: 1
-      };
-      const spaceRegex = /\s+/g;
-      const specNameRegex = /^spec$|^spec[-]*\w+$/i;
-      const terminologyRegex = /^def$|^ref$|^xref|^tref$/i;
-      const specCorpus = fs.readJsonSync(modulePath + '/assets/compiled/refs.json');
-      const containers = require('markdown-it-container');
-
-      /* 
-      `const md` is assigned an instance of the markdown-it parser configured with various plugins and extensions. This instance (md) is intended to be used later to parse and render Markdown strings.
-      
-      The md function (which is an instance of the markdown-it parser) takes a Markdown string as its primary argument. It is called elsewhere as follows: `md.render(doc)`
-      */
-      const md = require('markdown-it')({
-        html: true,
-        linkify: true,
-        typographer: true
-      })
-        .use(require('./src/markdown-it-extensions.js'), [
-          {
-            filter: type => type.match(terminologyRegex),
-            parse(token, type, primary) {
-              if (!primary) return;
-              if (type === 'def') {
-                definitions.push(token.info.args);
-                return token.info.args.reduce((acc, syn) => {
-                  return `<span id="term:${syn.replace(spaceRegex, '-').toLowerCase()}">${acc}</span>`;
-                }, primary);
-              }
-              else if (type === 'xref') {
-                // Get the URL for the external specification reference, or default to '#' if not found
-                const externalSpec = findExternalSpecByKey(config, token.info.args[0]);
-                const url = externalSpec?.gh_page || '#';
-
-                const term = token.info.args[1].replace(spaceRegex, '-').toLowerCase();
-                return `<a class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}"
-                href="${url}#term:${term}">${token.info.args[1]}</a>`;
-              }
-              else if (type === 'tref') {
-                return `<span class="transcluded-xref-term" id="term:${token.info.args[1]}">${token.info.args[1]}</span>`;
-              }
-              else {
-                references.push(primary);
-                return `<a class="term-reference" href="#term:${primary.replace(spaceRegex, '-').toLowerCase()}">${primary}</a>`;
-              }
-            }
-          },
-          {
-            filter: type => type.match(specNameRegex),
-            parse(token, type, name) {
-              if (name) {
-                let _name = name.replace(spaceRegex, '-').toUpperCase();
-                let spec = specCorpus[_name] ||
-                  specCorpus[_name.toLowerCase()] ||
-                  specCorpus[name.toLowerCase()] ||
-                  specCorpus[name];
-                if (spec) {
-                  spec._name = _name;
-                  let group = specGroups[type] = specGroups[type] || {};
-                  token.info.spec = group[_name] = spec;
-                }
-              }
-            },
-            render(token, type, name) {
-              if (name) {
-                let spec = token.info.spec;
-                if (spec) return `[<a class="spec-reference" href="#ref:${spec._name}">${spec._name}</a>]`;
-              }
-              else return renderRefGroup(type);
+      // 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();
+    }
+
+    // Function to fix broken definition list structures
+    /**
+     * This function repairs 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 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 { JSDOM } = require('jsdom');
+      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 && 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 transcluded terms but no main dl, we need to create one
+      if (transcludedTerms.length > 0 && dlElements.length === 0) {
+        // Create a new dl element with the right class
+        mainDl = document.createElement('dl');
+        mainDl.className = 'terms-and-definitions-list';
+
+        // Find a good location to insert it - use the first transcluded term's parent as reference
+        const firstTerm = transcludedTerms[0];
+        const insertPoint = firstTerm.parentNode;
+        insertPoint.parentNode.insertBefore(mainDl, insertPoint);
+      } else if (dlElements.length > 0) {
+        // Use the first terms-and-definitions-list as our main container
+        mainDl = dlElements[0];
+      } else {
+        // No dl and no transcluded terms, nothing to fix
+        return html;
+      }
+
+      // Now process all transcluded terms and other dt elements
+      transcludedTerms.forEach(dt => {
+        // Check if this dt is not already inside our main dl
+        if (dt.parentElement !== mainDl) {
+          // Move it into the main dl
+          const dtClone = dt.cloneNode(true);
+          mainDl.appendChild(dtClone);
+          dt.parentNode.removeChild(dt);
+        }
+      });
+
+      // First special case - handle transcluded-xref-term dt that comes BEFORE the main dl
+      const transcludedTermsBeforeMainDl = document.querySelectorAll('dt.transcluded-xref-term');
+
+      // Special handling for transcluded terms that appear BEFORE the main dl
+      transcludedTermsBeforeMainDl.forEach(dt => {
+        // Check if this dt is not already inside our main list
+        if (dt.parentElement !== mainDl) {
+          // This is a dt outside our main list - move it into the main dl
+          const dtClone = dt.cloneNode(true);
+          mainDl.appendChild(dtClone);
+          dt.parentNode.removeChild(dt);
+        }
+      });
+
+      // 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
+        const nextNode = currentNode.nextSibling;
+
+        // Handle different node types
+        if (currentNode.nodeType === 1) { // 1 = Element node
+          if (currentNode.tagName === 'DL') {
+            // Found another definition list - 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);
           }
-        ])
-        .use(require('markdown-it-attrs'))
-        .use(require('markdown-it-chart').default)
-        .use(require('markdown-it-deflist'))
-        .use(require('markdown-it-references'))
-        .use(require('markdown-it-icons').default, 'font-awesome')
-        .use(require('markdown-it-ins'))
-        .use(require('markdown-it-mark'))
-        .use(require('markdown-it-textual-uml'))
-        .use(require('markdown-it-sub'))
-        .use(require('markdown-it-sup'))
-        .use(require('markdown-it-task-lists'))
-        .use(require('markdown-it-multimd-table'), {
-          multiline: true,
-          rowspan: true,
-          headerless: true
-        })
-        .use(containers, 'notice', {
-          validate: function (params) {
-            let matches = params.match(/(\w+)\s?(.*)?/);
-            return matches && noticeTypes[matches[1]];
-          },
-          render: function (tokens, idx) {
-            let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/);
-            if (matches && tokens[idx].nesting === 1) {
-              let id;
-              let type = matches[1];
-              if (matches[2]) {
-                id = matches[2].trim().replace(/\s+/g, '-').toLowerCase();
-                if (noticeTitles[id]) id += '-' + noticeTitles[id]++;
-                else noticeTitles[id] = 1;
-              }
-              else id = type + '-' + noticeTypes[type]++;
-              return `<div id="${id}" class="notice ${type}"><a class="notice-link" href="#${id}">${type.toUpperCase()}</a>`;
-            }
-            else return '</div>\n';
+          else if (currentNode.tagName === 'DT') {
+            // Found a standalone dt - move it into the main dl
+            const dtClone = currentNode.cloneNode(true);
+            mainDl.appendChild(dtClone);
+            currentNode.parentNode.removeChild(currentNode);
           }
-        })
-        .use(require('markdown-it-prism'))
-        .use(require('markdown-it-toc-and-anchor').default, {
-          tocClassName: 'toc',
-          tocFirstLevel: 2,
-          tocLastLevel: 4,
-          tocCallback: (_md, _tokens, html) => toc = html,
-          anchorLinkSymbol: '#', // was: §
-          anchorClassName: 'toc-anchor'
-        })
-        .use(require('@traptitech/markdown-it-katex'))
-
-      async function render(spec, assets) {
-        try {
-          noticeTitles = {};
-          specGroups = {};
-          console.log('ℹ️ Rendering: ' + spec.title);
-
-          function interpolate(template, variables) {
-            return template.replace(/\${(.*?)}/g, (match, p1) => variables[p1.trim()]);
+          else if (currentNode.tagName === 'P' &&
+            (!currentNode.textContent || currentNode.textContent.trim() === '')) {
+            // Remove empty paragraphs - these break the list structure
+            currentNode.parentNode.removeChild(currentNode);
           }
+        }
 
-          const docs = await Promise.all(
-            (spec.markdown_paths || ['spec.md']).map(_path =>
-              fs.readFile(spec.spec_directory + _path, 'utf8')
-            )
-          );
+        // Move to the next node we saved earlier
+        currentNode = nextNode;
+      }
 
-          const features = (({ source, logo }) => ({ source, logo }))(spec);
-          if (spec.external_specs && !externalReferences) {
-            externalReferences = await fetchExternalSpecs(spec);
-          }
+      // Return the fixed HTML
+      return dom.serialize();
+    }
 
-              // Find the index of the terms-and-definitions-intro.md file
-          const termsIndex = (spec.markdown_paths || ['spec.md']).indexOf('terms-and-definitions-intro.md');
-          if (termsIndex !== -1) {
-                // Append the HTML string to the content of terms-and-definitions-intro.md. This string is used to create a div that is used to insert an alphabet index, and a div that is used as the starting point of the terminology index. The newlines are essential for the correct rendering of the markdown.
-            docs[termsIndex] += '\n\n<div id="terminology-section-start-h7vc6omi2hr2880"></div>\n\n';
-          }
+    async function render(spec, assets) {
+      try {
+        noticeTitles = {};
+        specGroups = {};
+        console.log('ℹ️ Rendering: ' + spec.title);
 
-          let doc = docs.join("\n");
-
-              // `doc` is markdown 
-          doc = applyReplacers(doc);
-
-          md[spec.katex ? "enable" : "disable"](katexRules);
-
-              // `render` is the rendered HTML
-          const render = md.render(doc);
-
-          const templateInterpolated = interpolate(template, {
-            title: spec.title,
-            description: spec.description,
-            author: spec.author,
-            toc: toc,
-            render: render,
-            assetsHead: assets.head,
-            assetsBody: assets.body,
-            assetsSvg: assets.svg,
-            features: Object.keys(features).join(' '),
-            externalReferences: JSON.stringify(externalReferences),
-            xtrefsData: xtrefsData,
-            specLogo: spec.logo,
-            specFavicon: spec.favicon,
-            specLogoLink: spec.logo_link,
-            spec: JSON.stringify(spec),
-            externalSpecsList: externalSpecsList,
-          });
+        function interpolate(template, variables) {
+          return template.replace(/\${(.*?)}/g, (match, p1) => variables[p1.trim()]);
+        }
 
-          const outputPath = path.join(spec.destination, 'index.html');
-          console.log('ℹ️ Attempting to write to:', outputPath);
+        const docs = await Promise.all(
+          (spec.markdown_paths || ['spec.md']).map(_path =>
+            fs.readFile(spec.spec_directory + _path, 'utf8')
+          )
+        );
 
-          // Use promisified version instead of callback
-          await fs.promises.writeFile(outputPath, templateInterpolated, 'utf8');
-          console.log(`✅ Successfully wrote ${outputPath}`);
+        const features = (({ source, logo }) => ({ source, logo }))(spec);
+        if (spec.external_specs && !externalReferences) {
+          externalReferences = await fetchExternalSpecs(spec);
+        }
 
-          validateReferences(references, definitions, render);
-          references = [];
-          definitions = [];
-        } catch (e) {
-          console.error("❌ Render error: " + e.message);
-          throw e;
+        // Find the index of the terms-and-definitions-intro.md file
+        const termsIndex = (spec.markdown_paths || ['spec.md']).indexOf('terms-and-definitions-intro.md');
+        if (termsIndex !== -1) {
+          // Append the HTML string to the content of terms-and-definitions-intro.md. This string is used to create a div that is used to insert an alphabet index, and a div that is used as the starting point of the terminology index. The newlines are essential for the correct rendering of the markdown.
+          docs[termsIndex] += '\n\n<div id="terminology-section-start-h7vc6omi2hr2880"></div>\n\n';
         }
+
+        let doc = docs.join("\n");
+
+        // `doc` is markdown 
+        doc = applyReplacers(doc);
+
+        md[spec.katex ? "enable" : "disable"](katexRules);
+
+        // `render` is the rendered HTML
+        let renderedHtml = md.render(doc);
+
+        // Apply the fix for broken definition list structures
+        renderedHtml = fixDefinitionListStructure(renderedHtml);
+
+        // Sort definition terms case-insensitively before final rendering
+        renderedHtml = sortDefinitionTermsInHtml(renderedHtml);
+
+        // Process external references to ensure they are inserted as raw HTML, not as JSON string
+        const externalReferencesHtml = Array.isArray(externalReferences) 
+          ? externalReferences.join('') 
+          : (externalReferences || '');
+
+        const templateInterpolated = interpolate(template, {
+          title: spec.title,
+          description: spec.description,
+          author: spec.author,
+          toc: toc,
+          render: renderedHtml,
+          assetsHead: assets.head,
+          assetsBody: assets.body,
+          assetsSvg: assets.svg,
+          features: Object.keys(features).join(' '),
+          externalReferences: externalReferencesHtml,
+          xtrefsData: xtrefsData,
+          specLogo: spec.logo,
+          specFavicon: spec.favicon,
+          specLogoLink: spec.logo_link,
+          spec: JSON.stringify(spec),
+          externalSpecsList: externalSpecsList,
+        });
+
+        const outputPath = path.join(spec.destination, 'index.html');
+        console.log('ℹ️ Attempting to write to:', outputPath);
+
+        // Use promisified version instead of callback
+        await fs.promises.writeFile(outputPath, templateInterpolated, 'utf8');
+        console.log(`✅ Successfully wrote ${outputPath}`);
+
+        validateReferences(references, definitions, renderedHtml);
+        references = [];
+        definitions = [];
+      } catch (e) {
+        console.error("❌ Render error: " + e.message);
+        throw e;
       }
+    }
 
+    try {
       config.specs.forEach(spec => {
         spec.spec_directory = normalizePath(spec.spec_directory);
         spec.destination = normalizePath(spec.output_path || spec.spec_directory);
-      
+
         if (!fs.existsSync(spec.destination)) {
           try {
             fs.mkdirSync(spec.destination, { recursive: true });
@@ -423,7 +662,7 @@ module.exports = async function (options = {}) {
             console.error('❌ Render failed:', e.message);
             process.exit(1);
           });
-        
+
         if (!options.nowatch) {
           gulp.watch(
             [spec.spec_directory + '**/*', '!' + path.join(spec.destination, 'index.html')],