spec-up-t 1.3.0 → 1.4.0

package/src/pipeline/references/fetch-terms-from-index.js

@@ -0,0 +1,198 @@
+/**
+ * @file fetch-terms-from-index.js
+ * @description Fetches term definitions from an external specification repository using either the published GitHub Pages site or the raw repository fallback.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { JSDOM } = require('jsdom');
+const axios = require('axios');
+const { getPath } = require('../../../config/paths');
+const Logger = require('../../utils/logger');
+
+const CACHE_DIR = getPath('githubcache');
+
+async function getFileCommitHash(token, owner, repo, filePath, headers) {
+    try {
+        const normalizedPath = filePath.replace(/^\//, '');
+        const commitsUrl = `https://api.github.com/repos/${owner}/${repo}/commits?path=${normalizedPath}&per_page=1`;
+        Logger.process(`Fetching latest commit for file: ${commitsUrl}`);
+
+        const response = await axios.get(commitsUrl, { headers });
+        if (response.status !== 200 || !Array.isArray(response.data) || response.data.length === 0) {
+            Logger.error(`Could not find commit information for ${filePath}`);
+            return null;
+        }
+
+        return response.data[0].sha;
+    } catch (error) {
+        Logger.error(`Error fetching commit hash: ${error.message}`);
+        return null;
+    }
+}
+
+async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
+    try {
+        const headers = token ? { Authorization: `token ${token}` } : {};
+        let indexHtmlUrl;
+        let commitHash = null;
+
+        if (options.ghPageUrl) {
+            indexHtmlUrl = options.ghPageUrl.endsWith('/')
+                ? `${options.ghPageUrl}index.html`
+                : `${options.ghPageUrl}/index.html`;
+            Logger.process(`Fetching index.html from GitHub Pages: ${indexHtmlUrl}`);
+
+            try {
+                const mainBranchUrl = `https://api.github.com/repos/${owner}/${repo}/branches/main`;
+                const branchResponse = await axios.get(mainBranchUrl, { headers });
+                if (branchResponse.status === 200) {
+                    commitHash = branchResponse.data.commit.sha;
+                    Logger.success(`Got commit hash from main branch: ${commitHash}`);
+                }
+            } catch (error) {
+                Logger.error(`Could not get commit hash from main branch: ${error.message}`);
+            }
+        } else {
+            Logger.warn('No GitHub Pages URL provided, falling back to repository method');
+            const specsJsonUrl = `https://api.github.com/repos/${owner}/${repo}/contents/specs.json`;
+            Logger.process(`Fetching specs.json from: ${specsJsonUrl}`);
+
+            const specsJsonResponse = await axios.get(specsJsonUrl, { headers });
+            if (specsJsonResponse.status !== 200) {
+                Logger.error(`Could not find specs.json in repository ${owner}/${repo}`);
+                return null;
+            }
+
+            const specsJsonContent = Buffer.from(specsJsonResponse.data.content, 'base64').toString('utf8');
+            const specsJson = JSON.parse(specsJsonContent);
+            const outputPath = specsJson.specs?.[0]?.output_path;
+            if (!outputPath) {
+                Logger.error(`No output_path found in specs.json for repository ${owner}/${repo}`);
+                return null;
+            }
+
+            const normalizedOutputPath = outputPath.replace(/^\.\//, '').replace(/\/$/, '');
+            const indexHtmlPath = `${normalizedOutputPath}/index.html`;
+            indexHtmlUrl = `https://raw.githubusercontent.com/${owner}/${repo}/main/${indexHtmlPath}`;
+            Logger.process(`Fetching index.html from raw repository: ${indexHtmlUrl}`);
+
+            commitHash = await getFileCommitHash(token, owner, repo, indexHtmlPath, headers);
+            if (!commitHash) {
+                Logger.warn('Could not get commit hash for index.html, continuing without it');
+            }
+        }
+
+        const indexHtmlResponse = await axios.get(indexHtmlUrl, { headers });
+        if (indexHtmlResponse.status !== 200) {
+            Logger.error(`Could not find index.html at ${indexHtmlUrl}`);
+            return null;
+        }
+
+        const dom = new JSDOM(indexHtmlResponse.data);
+        const document = dom.window.document;
+        const termDlList = document.querySelector('dl.terms-and-definitions-list');
+        if (!termDlList) {
+            Logger.error(`No terms-and-definitions-list found in ${indexHtmlUrl}`);
+            return null;
+        }
+
+        const terms = [];
+        const dtElements = termDlList.querySelectorAll('dt');
+        dtElements.forEach(dt => {
+            const termSpan = dt.querySelector('span[id^="term:"]');
+            if (!termSpan) {
+                return;
+            }
+
+            let termText = '';
+            termSpan.childNodes.forEach(node => {
+                if (node.nodeType === dom.window.Node.TEXT_NODE) {
+                    termText += node.textContent.trim();
+                }
+            });
+
+            if (!termText) {
+                termText = termSpan.textContent.trim();
+            }
+
+            if (!termText) {
+                return;
+            }
+
+            const definitions = [];
+            let pointer = dt.nextElementSibling;
+            while (pointer && pointer.tagName.toLowerCase() === 'dd') {
+                definitions.push(pointer.outerHTML);
+                pointer = pointer.nextElementSibling;
+            }
+
+            terms.push({ term: termText, definition: definitions.join('\n') });
+        });
+
+        const timestamp = Date.now();
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+        const outputFileName = `${timestamp}-${owner}-${repo}-terms.json`;
+        const outputFilePath = path.join(CACHE_DIR, outputFileName);
+
+        const result = {
+            timestamp,
+            repository: `${owner}/${repo}`,
+            terms,
+            sha: commitHash,
+            avatarUrl: null,
+            outputFileName
+        };
+
+        fs.writeFileSync(outputFilePath, JSON.stringify(result, null, 2));
+        Logger.success(`Saved ${terms.length} terms to ${outputFilePath}`);
+
+        return result;
+    } catch (error) {
+        if (error.response) {
+            if (error.response.status === 404) {
+                Logger.error(`Resource not found: ${error.config.url}`);
+            } else if (error.response.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') {
+                const resetTime = new Date(Number(error.response.headers['x-ratelimit-reset']) * 1000);
+                Logger.error(`GitHub API rate limit exceeded. Try again after ${resetTime.toLocaleString()}`);
+            } else {
+                Logger.error(`Error fetching data: ${error.response.status} ${error.response.statusText}`);
+            }
+        } else {
+            Logger.error(`Error fetching term: ${error.message}`);
+        }
+        return null;
+    }
+}
+
+async function fetchTermsFromIndex(token, term, owner, repo, termsDir, options = {}) {
+    const allTermsData = await fetchAllTermsFromIndex(token, owner, repo, options);
+    if (!allTermsData || !Array.isArray(allTermsData.terms)) {
+        return null;
+    }
+
+    const foundTerm = allTermsData.terms.find(t => t.term.toLowerCase() === term.toLowerCase());
+    if (!foundTerm) {
+        Logger.error(`Term "${term}" not found in repository ${owner}/${repo}`);
+        return null;
+    }
+
+    Logger.success(`Found term '${term}' in repository ${owner}/${repo}`);
+    return {
+        term: foundTerm.term,
+        content: foundTerm.definition,
+        sha: allTermsData.sha,
+        repository: {
+            owner: {
+                login: owner,
+                avatar_url: allTermsData.avatarUrl
+            },
+            name: repo
+        }
+    };
+}
+
+module.exports = {
+    fetchTermsFromIndex,
+    fetchAllTermsFromIndex
+};

package/src/pipeline/references/match-term.js

@@ -0,0 +1,34 @@
+/**
+ * @file match-term.js
+ * @description Utilities for matching a specific term within a [[def: ...]] definition block.
+ */
+
+const { isLineWithDefinition } = require('../../utils/is-line-with-definition');
+const Logger = require('../../utils/logger');
+
+function matchTerm(text, term) {
+    if (!text || typeof text !== 'string') {
+        Logger.warn('Nothing to match for term:', term);
+        return false;
+    }
+
+    const firstLine = text.split('\n')[0].trim();
+    if (!isLineWithDefinition(firstLine)) {
+        Logger.warn('String does not start with `[[def:` or end with `]]`');
+        return false;
+    }
+
+    const startPos = firstLine.indexOf('[[def:') + 6;
+    const endPos = firstLine.indexOf(']]');
+    if (startPos === -1 || endPos === -1) {
+        return false;
+    }
+
+    const relevantPart = firstLine.substring(startPos, endPos);
+    const termsArray = relevantPart.split(',').map(entry => entry.trim());
+    return termsArray.includes(term);
+}
+
+module.exports = {
+    matchTerm
+};

package/src/{collectExternalReferences/matchTerm.test.js → pipeline/references/match-term.test.js}

@@ -1,30 +1,36 @@
-const { matchTerm } = require('./matchTerm');
+const { matchTerm } = require('./match-term');
 
+// Tests for matching terms within definition markup
 describe('matchTerm', () => {
+    // Test: Can the system find terms that exist in definition markup?
     test('returns true when the term is found in a correctly formatted definition', () => {
         const text = '[[def: term1, term2]]\nSome additional text';
         expect(matchTerm(text, 'term1')).toBe(true);
         expect(matchTerm(text, 'term2')).toBe(true);
     });
 
+    // Test: Does the system correctly identify when a term is not present?
     test('returns false when the term is not found in the definition', () => {
         const text = '[[def: term1, term2]]\nSome additional text';
         expect(matchTerm(text, 'term3')).toBe(false);
     });
 
+    // Test: Does the system handle invalid input gracefully?
     test('returns false when the text is null or not a string', () => {
         expect(matchTerm(null, 'term1')).toBe(false);
         expect(matchTerm(123, 'term1')).toBe(false);
     });
 
+    // Test: Does the system require proper definition markup format?
     test('returns false when the first line is not a valid definition', () => {
         const text = 'Invalid definition line\n[[def: term1, term2]]';
         expect(matchTerm(text, 'term1')).toBe(false);
     });
 
+    // Test: Can the system handle whitespace variations in markup?
     test('handles extra spaces correctly', () => {
         const text = '[[def:   term1  ,   term2   ]]';
         expect(matchTerm(text, 'term1')).toBe(true);
         expect(matchTerm(text, 'term2')).toBe(true);
     });
-});
+});

package/src/pipeline/references/process-xtrefs-data.js

@@ -0,0 +1,94 @@
+const fs = require('fs');
+const path = require('path');
+const { fetchAllTermsFromIndex } = require('./fetch-terms-from-index');
+const { getPath } = require('../../../config/paths');
+const Logger = require('../../utils/logger');
+
+const CACHE_DIR = getPath('githubcache');
+
+async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, outputPathJS, outputPathJSTimeStamped) {
+    try {
+        if (!fs.existsSync(CACHE_DIR)) {
+            fs.mkdirSync(CACHE_DIR, { recursive: true });
+        }
+
+        allXTrefs.xtrefs = allXTrefs.xtrefs.filter(xtref => {
+            if (!xtref.owner || !xtref.repo || !xtref.repoUrl) {
+                Logger.warn(`Removing incomplete reference: ${xtref.externalSpec}, ${xtref.term}`);
+                return false;
+            }
+            return true;
+        });
+
+        const xrefsByRepo = allXTrefs.xtrefs.reduce((groups, xtref) => {
+            const repoKey = `${xtref.owner}/${xtref.repo}`;
+            if (!groups[repoKey]) {
+                groups[repoKey] = {
+                    owner: xtref.owner,
+                    repo: xtref.repo,
+                    xtrefs: []
+                };
+            }
+            groups[repoKey].xtrefs.push(xtref);
+            return groups;
+        }, {});
+
+        Logger.highlight(`Grouped ${allXTrefs.xtrefs.length} terms into ${Object.keys(xrefsByRepo).length} repositories`);
+
+        for (const repoKey of Object.keys(xrefsByRepo)) {
+            const repoGroup = xrefsByRepo[repoKey];
+            Logger.process(`Processing repository: ${repoKey} (${repoGroup.xtrefs.length} terms)`);
+
+            const ghPageUrl = repoGroup.xtrefs[0]?.ghPageUrl;
+            const allTermsData = await fetchAllTermsFromIndex(
+                GITHUB_API_TOKEN,
+                repoGroup.owner,
+                repoGroup.repo,
+                { ghPageUrl }
+            );
+
+            if (!allTermsData) {
+                Logger.error(`Could not fetch terms from repository ${repoKey}`);
+                repoGroup.xtrefs.forEach(xtref => {
+                    xtref.commitHash = 'not found';
+                    xtref.content = 'This term was not found in the external repository.';
+                    xtref.avatarUrl = null;
+                });
+                continue;
+            }
+
+            for (const xtref of repoGroup.xtrefs) {
+                const foundTerm = allTermsData.terms.find(
+                    t => t.term.toLowerCase() === xtref.term.toLowerCase()
+                );
+
+                if (foundTerm) {
+                    xtref.commitHash = allTermsData.sha;
+                    xtref.content = foundTerm.definition;
+                    xtref.avatarUrl = allTermsData.avatarUrl;
+                    Logger.success(`Match found for term: ${xtref.term} in ${xtref.externalSpec}`);
+                } else {
+                    xtref.commitHash = 'not found';
+                    xtref.content = 'This term was not found in the external repository.';
+                    xtref.avatarUrl = null;
+                    Logger.error(`Origin: ${xtref.sourceFile || xtref.sourceFiles.join(', ')} 👉 No match found for term: ${xtref.term} in ${xtref.externalSpec} (${repoKey})`);
+                }
+            }
+
+            Logger.success(`Finished processing repository: ${repoKey}`);
+            Logger.separator();
+        }
+
+        const allXTrefsStr = JSON.stringify(allXTrefs, null, 2);
+        fs.writeFileSync(outputPathJSON, allXTrefsStr, 'utf8');
+        const jsPayload = `const allXTrefs = ${allXTrefsStr};`;
+    fs.writeFileSync(outputPathJS, jsPayload, 'utf8');
+    fs.writeFileSync(outputPathJSTimeStamped, jsPayload, 'utf8');
+    } catch (error) {
+        Logger.error('An error occurred:', error);
+    }
+}
+
+module.exports = {
+    processXTrefsData
+};

package/src/pipeline/references/xtref-utils.js

@@ -0,0 +1,166 @@
+/**
+ * @file Utility helpers for identifying, parsing, and aggregating external term references (xref/tref).
+ *
+ * These functions were previously embedded in the monolithic `collect-external-references` module.
+ * Splitting them into a dedicated utility keeps the collection pipeline focused on orchestration
+ * and makes the primitives easier to reuse in other reference-aware stages.
+ */
+
+const { externalReferences, utils } = require('../../utils/regex-patterns');
+
+/**
+ * Checks if a specific xtref is present in the markdown content.
+ *
+ * @param {{ externalSpec: string, term: string }} xtref - Reference descriptor.
+ * @param {string} markdownContent - Markdown text to inspect.
+ * @returns {boolean} True when the reference is found.
+ */
+function isXTrefInMarkdown(xtref, markdownContent) {
+    const regexTerm = utils.createXTrefRegex(xtref.externalSpec, xtref.term);
+    return regexTerm.test(markdownContent);
+}
+
+/**
+ * Finds a reference across multiple markdown files.
+ *
+ * @param {{ externalSpec: string, term: string }} xtref - Reference descriptor.
+ * @param {Map<string, string>} fileContents - Markdown contents keyed by filename.
+ * @returns {boolean} True when the reference is found in any file.
+ */
+function isXTrefInAnyFile(xtref, fileContents) {
+    for (const content of fileContents.values()) {
+        if (isXTrefInMarkdown(xtref, content)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Adds a pre-parsed xtref object to the aggregated collection.
+ * This function handles deduplication and source file tracking.
+ *
+ * @param {object} xtrefObject - Pre-parsed xtref object from template-tag-parser
+ * @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection
+ * @param {string|null} filename - Originating filename for bookkeeping
+ * @returns {{ xtrefs: Array<object> }} Updated reference collection
+ */
+function addXtrefToCollection(xtrefObject, allXTrefs, filename = null) {
+    const referenceType = xtrefObject.referenceType;
+    const cleanXTrefObj = { ...xtrefObject };
+    delete cleanXTrefObj.referenceType;
+
+    const existingIndex = allXTrefs?.xtrefs?.findIndex(existingXTref =>
+        existingXTref.term === cleanXTrefObj.term &&
+        existingXTref.externalSpec === cleanXTrefObj.externalSpec
+    );
+
+    if (existingIndex === -1) {
+        if (filename) {
+            cleanXTrefObj.sourceFiles = [{ file: filename, type: referenceType }];
+        }
+        allXTrefs.xtrefs.push(cleanXTrefObj);
+        return allXTrefs;
+    }
+
+    if (!filename) {
+        return allXTrefs;
+    }
+
+    const existingXTref = allXTrefs.xtrefs[existingIndex];
+
+    // Update the existing entry with new data to handle changes in aliases
+    // Preserve the existing sourceFiles array and extend it with new entries
+    const existingSourceFiles = existingXTref.sourceFiles || [];
+
+    // Smart merge: Priority is given to tref over xref for properties like aliases
+    // If the new reference is an xref and existing has tref data, preserve tref properties
+    const hasExistingTref = existingSourceFiles.some(sf => sf.type === 'tref');
+    const isNewXref = referenceType === 'xref';
+
+    if (hasExistingTref && isNewXref) {
+        // Don't overwrite tref data with xref data - just merge xref aliases
+        // Keep existing tref aliases and properties, but add xref aliases
+        if (cleanXTrefObj.xrefAliases && cleanXTrefObj.xrefAliases.length > 0) {
+            existingXTref.xrefAliases = cleanXTrefObj.xrefAliases;
+            existingXTref.firstXrefAlias = cleanXTrefObj.firstXrefAlias;
+        }
+    } else if (!hasExistingTref && isNewXref) {
+        // New xref with no existing tref - initialize empty tref arrays
+        Object.assign(existingXTref, cleanXTrefObj);
+        if (!existingXTref.trefAliases) {
+            existingXTref.trefAliases = [];
+        }
+    } else {
+        // Update with new tref data (either new tref, or updating existing tref)
+        Object.assign(existingXTref, cleanXTrefObj);
+        
+        // Ensure xref arrays exist if not present in new object
+        if (!cleanXTrefObj.xrefAliases && !existingXTref.xrefAliases) {
+            existingXTref.xrefAliases = [];
+        }
+
+        // Handle properties that should be removed when not present in the new object
+        if (!cleanXTrefObj.hasOwnProperty('firstTrefAlias') && existingXTref.hasOwnProperty('firstTrefAlias')) {
+            delete existingXTref.firstTrefAlias;
+        }
+        if (!cleanXTrefObj.hasOwnProperty('firstXrefAlias') && existingXTref.hasOwnProperty('firstXrefAlias')) {
+            delete existingXTref.firstXrefAlias;  
+        }
+    }
+
+    // Restore and update the sourceFiles array
+    existingXTref.sourceFiles = existingSourceFiles;
+
+    if (filename) {
+        const newEntry = { file: filename, type: referenceType };
+        const alreadyTracked = existingXTref.sourceFiles.some(entry =>
+            entry.file === filename && entry.type === referenceType
+        );
+
+        if (!alreadyTracked) {
+            existingXTref.sourceFiles.push(newEntry);
+        }
+    }
+
+    return allXTrefs;
+}
+
+/**
+ * Adds new references discovered in markdown to an aggregated collection.
+ * This function uses external parsing to maintain separation of concerns
+ * between parsing and collection logic.
+ *
+ * @param {string} markdownContent - Markdown text to scan.
+ * @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection.
+ * @param {string|null} filename - Originating filename for bookkeeping.
+ * @param {function} processXTrefObject - Parsing function for xtref strings.
+ * @returns {{ xtrefs: Array<object> }} Updated reference collection.
+ */
+function addNewXTrefsFromMarkdown(markdownContent, allXTrefs, filename = null, processXTrefObject) {
+    if (!processXTrefObject) {
+        throw new Error('processXTrefObject function is required. Import from template-tag-parser.');
+    }
+
+    const regex = externalReferences.allXTrefs;
+
+    if (!regex.test(markdownContent)) {
+        return allXTrefs;
+    }
+
+    const xtrefs = markdownContent.match(regex) || [];
+
+    xtrefs.forEach(rawXtref => {
+        const xtrefObject = processXTrefObject(rawXtref);
+        addXtrefToCollection(xtrefObject, allXTrefs, filename);
+    });
+
+    return allXTrefs;
+}
+
+module.exports = {
+    isXTrefInMarkdown,
+    isXTrefInAnyFile,
+    addXtrefToCollection,
+    addNewXTrefsFromMarkdown
+};

package/src/pipeline/rendering/render-spec-document.js

@@ -0,0 +1,146 @@
+/**
+ * Handles the core rendering logic for a single spec.
+ * Processes markdown files, renders HTML, applies fixes, and writes output.
+ * It takes shared variables and config as parameters to maintain modularity.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const { fetchExternalSpecs, validateReferences, mergeXrefTermsIntoAllXTrefs } = require('../references/external-references-service.js');
+const { processEscapedTags, restoreEscapedTags } = require('../preprocessing/escape-placeholder-utils.js');
+const { sortDefinitionTermsInHtml, fixDefinitionListStructure } = require('../postprocessing/definition-list-postprocessor.js');
+const { getGithubRepoInfo } = require('../../utils/git-info.js');
+const { templateTags } = require('../../utils/regex-patterns.js');
+
+const { createScriptElementWithXTrefDataForEmbeddingInHtml, applyReplacers } = require('./render-utils.js');
+
+async function render(spec, assets, sharedVars, config, template, assetsGlobal, Logger, md, externalSpecsList) {
+  let { externalReferences } = sharedVars;
+
+  try {
+    global.noticeTitles = {};
+    global.specGroups = {};
+    Logger.info('Rendering: ' + spec.title);
+
+    function interpolate(template, variables) {
+      return template.replace(templateTags.variableInterpolation, (match, p1) => variables[p1.trim()]);
+    }
+
+    // Add current date in 'DD Month YYYY' format for template injection
+    const date = new Date();
+    const day = String(date.getDate()).padStart(2, '0');
+    const month = date.toLocaleString('en-US', { month: 'long' });
+    const year = date.getFullYear();
+    const currentDate = `${day} ${month} ${year}`;
+
+    // Add universal timestamp in ISO 8601 format for template injection
+    const universalTimestamp = date.toISOString();
+
+    // Read all markdown files into an array
+    const docs = await Promise.all(
+      (spec.markdown_paths || ['spec.md']).map(_path =>
+        fs.readFile(spec.spec_directory + _path, 'utf8')
+      )
+    );
+
+    const features = (({ source, logo }) => ({ source, logo }))(spec);
+    if (spec.external_specs && !externalReferences) {
+      // Fetch xref terms and merge them into allXTrefs instead of creating DOM HTML
+      const xrefTerms = await fetchExternalSpecs(spec);
+
+      // Define paths for the xtrefs data files
+      const outputPathJSON = path.join('.cache', 'xtrefs-data.json');
+      const outputPathJS = path.join('.cache', 'xtrefs-data.js');
+
+      // Merge xref terms into the unified allXTrefs structure
+      await mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPathJS);
+
+      // Set flag to indicate external references have been processed
+      externalReferences = true; // Changed from HTML array to boolean flag
+    }
+
+    // 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"></div>\n\n';
+    }
+
+    // Set up file tracking for definitions before rendering
+    for (let i = 0; i < docs.length; i++) {
+      global.currentFile = spec.markdown_paths[i] || 'unknown';
+      docs[i] = `<!-- file: ${global.currentFile} -->\n${docs[i]}`;
+    }
+
+    // Concatenate all file contents into one string, separated by newlines
+    let doc = docs.join("\n");
+
+    // Handles backslash escape mechanism for substitution tags
+    // Phase 1: Pre-processing - Handle escaped tags
+    doc = processEscapedTags(doc);
+
+    // Handles backslash escape mechanism for substitution tags
+    // Phase 2: Tag Processing - Apply normal substitution logic
+    doc = applyReplacers(doc);
+
+    md[spec.katex ? "enable" : "disable"](['math_block', 'math_inline']);
+
+    // `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);
+
+    // Handles backslash escape mechanism for substitution tags
+    // Phase 3: Post-processing - Restore escaped sequences as literals
+    renderedHtml = restoreEscapedTags(renderedHtml);
+
+    // External references are now stored in allXTrefs instead of DOM HTML
+    // No longer need to inject external references HTML into the template
+
+    const templateInterpolated = interpolate(template, {
+      title: spec.title,
+      description: spec.description,
+      author: spec.author,
+      toc: global.toc,
+      render: renderedHtml,
+      assetsHead: assets.head,
+      assetsBody: assets.body,
+      assetsSvg: assets.svg,
+      features: Object.keys(features).join(' '),
+      externalReferences: '', // No longer inject DOM HTML - xrefs are in allXTrefs
+      xtrefsData: createScriptElementWithXTrefDataForEmbeddingInHtml(),
+      specLogo: spec.logo,
+      specFavicon: spec.favicon,
+      specLogoLink: spec.logo_link,
+      spec: JSON.stringify(spec),
+      externalSpecsList: externalSpecsList,
+      currentDate: currentDate,
+      universalTimestamp: universalTimestamp,
+      githubRepoInfo: getGithubRepoInfo(spec)
+    });
+
+    const outputPath = path.join(spec.destination, 'index.html');
+    Logger.info('Attempting to write to:', outputPath);
+
+    // Use promisified version instead of callback
+    await fs.promises.writeFile(outputPath, templateInterpolated, 'utf8');
+    Logger.success(`Successfully wrote ${outputPath}`);
+
+    validateReferences(global.references, global.definitions, renderedHtml);
+    global.references = [];
+    global.definitions = [];
+  } catch (e) {
+    Logger.error("Render error: " + e.message);
+    throw e;
+  }
+
+  // Update sharedVars
+  sharedVars.externalReferences = externalReferences;
+}
+
+module.exports = { render };