spec-up-t 1.2.7 → 1.2.9

package/assets/css/highlight-heading-plus-sibling-nodes.css

@@ -0,0 +1,6 @@
+.highlight2 {
+    padding-left: 1em;
+    padding-right: 1em;
+    border: 1px dashed #71bbe6;
+    background: #a9dde03b;
+}

package/assets/css/index.css

@@ -3,6 +3,15 @@
   /* Matches sticky header height */
 }
 
+
+/*
+- When a URL fragment targets an element,
+the `:target` pseudo-class triggers the corresponding CSS rules.
+- If the body lacks the hashscroll attribute: 
+   - The targeted element gets highlighted with an animation (highlight-target).
+   - Its parent <dt>(if applicable) gets highlighted with a different animation (highlight-target-parent-dt).
+- These animations visually emphasize the targeted element and its parent for better user experience.
+*/
 body:not([hashscroll]) *:target {
   animation: highlight-target 3.5s 0.25s ease;
 }

package/assets/js/collapse-definitions.js

@@ -227,12 +227,6 @@ function collapseDefinitions() {
             button.style.right = `${window.innerWidth - buttonRect.right}px`;
             button.style.zIndex = '1000';
 
-            // Add highlight effect
-            dtElement.classList.add('highlight');
-            setTimeout(() => {
-                dtElement.classList.remove('highlight');
-            }, 0);
-
             // Toggle visibility which might change layout
             toggleVisibility();
 

package/assets/js/highlight-heading-plus-sibling-nodes.js

@@ -0,0 +1,259 @@
+/**
+ * @fileoverview Provides functionality to highlight headings and their following sibling nodes
+ * when anchor links are clicked. This module uses event delegation to handle link clicks
+ * and dynamically wraps content sections with highlighting divs.
+ * 
+ * @author Generated by AI Assistant
+ * @version 1.0.0
+ */
+
+/**
+ * Highlights a heading and its following sibling nodes until the next heading of the same level.
+ * Only processes headings h2-h6, excluding h1 elements.
+ * 
+ * @param {string} anchor - The anchor string (e.g., "#linking-to-this-glossary")
+ * @returns {boolean} True if highlighting was successful, false otherwise
+ * 
+ * @example
+ * // Highlight heading with id "section-1" and its content
+ * highlightHeadingSection("#section-1");
+ * 
+ * @example
+ * // Use with anchor from URL hash
+ * highlightHeadingSection(window.location.hash);
+ */
+function highlightHeadingSection(anchor) {
+    // Validate input parameter
+    if (!anchor || typeof anchor !== 'string' || !anchor.startsWith('#')) {
+        console.warn('Invalid anchor provided:', anchor);
+        return false;
+    }
+
+    // Remove existing highlights before adding new ones
+    removeExistingHighlights();
+
+    // Extract the element ID from the anchor
+    const elementId = anchor.substring(1);
+    const targetElement = document.getElementById(elementId);
+
+    if (!targetElement) {
+        console.warn('Element with ID not found:', elementId);
+        return false;
+    }
+
+    // Check if the target element is a valid heading (h2-h6)
+    const headingLevel = getHeadingLevel(targetElement);
+    if (headingLevel === null) {
+        console.info('Target element is not a valid heading (h2-h6):', elementId);
+        return false;
+    }
+
+    // Find all sibling nodes until the next heading of the same level
+    const nodesToHighlight = collectHeadingSiblings(targetElement, headingLevel);
+
+    // Wrap the collected nodes with highlight div
+    wrapNodesWithHighlight(nodesToHighlight);
+
+    return true;
+}
+
+/**
+ * Determines if an element is a heading and returns its level.
+ * Only considers h2-h6 elements as valid headings.
+ * 
+ * @param {Element} element - The DOM element to check
+ * @returns {number|null} The heading level (2-6) or null if not a valid heading
+ * 
+ * @example
+ * const level = getHeadingLevel(document.querySelector('h3')); // Returns 3
+ * const invalid = getHeadingLevel(document.querySelector('h1')); // Returns null
+ */
+function getHeadingLevel(element) {
+    const tagName = element.tagName.toLowerCase();
+    const headingMatch = tagName.match(/^h([2-6])$/);
+    return headingMatch ? parseInt(headingMatch[1], 10) : null;
+}
+
+/**
+ * Collects a heading element and all its following sibling nodes until the next
+ * heading of the same or higher level in the hierarchy.
+ * 
+ * @param {Element} headingElement - The heading element to start from
+ * @param {number} headingLevel - The level of the heading (2-6)
+ * @returns {Element[]} Array of elements to be highlighted
+ * 
+ * @example
+ * const h3Element = document.querySelector('#my-section');
+ * const siblings = collectHeadingSiblings(h3Element, 3);
+ * // Returns [h3Element, ...following siblings until next h3 or higher]
+ */
+function collectHeadingSiblings(headingElement, headingLevel) {
+    const nodesToHighlight = [headingElement];
+    let currentNode = headingElement.nextElementSibling;
+
+    while (currentNode) {
+        const currentHeadingLevel = getHeadingLevel(currentNode);
+        
+        // Stop if we encounter a heading of the same or higher level
+        if (currentHeadingLevel !== null && currentHeadingLevel <= headingLevel) {
+            break;
+        }
+
+        nodesToHighlight.push(currentNode);
+        currentNode = currentNode.nextElementSibling;
+    }
+
+    return nodesToHighlight;
+}
+
+/**
+ * Wraps a collection of DOM nodes with a highlighting div element.
+ * Creates a div with class "highlight2" and moves all nodes inside it.
+ * 
+ * @param {Element[]} nodes - Array of DOM elements to wrap
+ * @returns {Element|null} The created wrapper div or null if no nodes provided
+ * 
+ * @example
+ * const nodes = [headingEl, paragraphEl, listEl];
+ * const wrapper = wrapNodesWithHighlight(nodes);
+ * // Creates: <div class="highlight2">...nodes...</div>
+ */
+function wrapNodesWithHighlight(nodes) {
+    if (!nodes || nodes.length === 0) {
+        return null;
+    }
+
+    // Create the highlight wrapper div
+    const highlightDiv = document.createElement('div');
+    highlightDiv.className = 'highlight2';
+
+    // Insert the wrapper before the first node
+    const firstNode = nodes[0];
+    firstNode.parentNode.insertBefore(highlightDiv, firstNode);
+
+    // Move all nodes into the wrapper
+    nodes.forEach(node => {
+        highlightDiv.appendChild(node);
+    });
+
+    return highlightDiv;
+}
+
+/**
+ * Removes all existing highlight wrappers from the document.
+ * This ensures only one section is highlighted at a time.
+ * 
+ * @returns {number} The number of highlight divs removed
+ * 
+ * @example
+ * const removedCount = removeExistingHighlights();
+ * console.log(`Removed ${removedCount} existing highlights`);
+ */
+function removeExistingHighlights() {
+    const existingHighlights = document.querySelectorAll('.highlight2');
+    let removedCount = 0;
+
+    existingHighlights.forEach(highlight => {
+        // Move all children back to the parent before removing the wrapper
+        const parent = highlight.parentNode;
+        while (highlight.firstChild) {
+            parent.insertBefore(highlight.firstChild, highlight);
+        }
+        parent.removeChild(highlight);
+        removedCount++;
+    });
+
+    return removedCount;
+}
+
+/**
+ * Handles click events on anchor links and triggers heading highlighting.
+ * Uses event delegation to handle dynamically added links.
+ * 
+ * @param {Event} event - The click event object
+ * @returns {void}
+ * 
+ * @example
+ * // This function is automatically called when anchor links are clicked
+ * // due to the event delegation setup in initializeAnchorHighlighting()
+ */
+function handleAnchorClick(event) {
+    const target = event.target;
+    
+    // Check if the clicked element is a link with an href containing a hash
+    if (target.tagName.toLowerCase() !== 'a') {
+        return;
+    }
+
+    const href = target.getAttribute('href');
+    if (!href || !href.includes('#')) {
+        return;
+    }
+
+    // Extract the anchor part from the href
+    const anchorPart = href.substring(href.indexOf('#'));
+    
+    // Only process if it's an internal anchor (starts with #)
+    if (anchorPart.startsWith('#') && anchorPart.length > 1) {
+        // Small delay to allow browser navigation to complete
+        setTimeout(() => {
+            highlightHeadingSection(anchorPart);
+        }, 100);
+    }
+}
+
+/**
+ * Initializes the anchor link highlighting functionality using event delegation.
+ * Sets up a single click event listener on the document that handles all anchor clicks.
+ * This approach is more efficient than attaching individual listeners to each link.
+ * 
+ * @returns {void}
+ * 
+ * @example
+ * // Initialize the highlighting system
+ * initializeAnchorHighlighting();
+ * 
+ * // Now all anchor links will automatically trigger highlighting
+ * // when clicked, including dynamically added links
+ */
+function initializeAnchorHighlighting() {
+    // Use event delegation to handle all anchor clicks
+    document.addEventListener('click', handleAnchorClick);
+    
+    // Also handle direct navigation to anchors (e.g., page load with hash)
+    if (window.location.hash) {
+        // Delay to ensure DOM is fully loaded
+        setTimeout(() => {
+            highlightHeadingSection(window.location.hash);
+        }, 200);
+    }
+    
+    // Handle browser back/forward navigation
+    window.addEventListener('hashchange', () => {
+        if (window.location.hash) {
+            highlightHeadingSection(window.location.hash);
+        } else {
+            removeExistingHighlights();
+        }
+    });
+}
+
+// Auto-initialize when DOM is ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initializeAnchorHighlighting);
+} else {
+    // DOM is already loaded
+    initializeAnchorHighlighting();
+}
+
+// Export functions for potential external use
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        highlightHeadingSection,
+        getHeadingLevel,
+        collectHeadingSiblings,
+        wrapNodesWithHighlight,
+        removeExistingHighlights,
+        initializeAnchorHighlighting
+    };
+}

package/config/asset-map.json

@@ -26,6 +26,7 @@
       "assets/css/image-full-size.css",
       "assets/css/add-bootstrap-classes-to-images.css",
       "assets/css/horizontal-scroll-hint.css",
+      "assets/css/highlight-heading-plus-sibling-nodes.css",
       "assets/css/index.css"
     ],
     "js": [
@@ -72,6 +73,7 @@
       "assets/js/horizontal-scroll-hint.js",
       "assets/js/add-bootstrap-classes-to-images.js",
       "assets/js/image-full-size.js",
+      "assets/js/highlight-heading-plus-sibling-nodes.js",
       "assets/js/bootstrap.bundle.min.js"
     ]
   }

package/gulpfile.js

@@ -19,9 +19,15 @@ async function fetchSpecRefs() {
   return Promise.all([
     axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/ietf.json'),
     axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/w3c.json'),
-    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/whatwg.json')
+    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/whatwg.json'),
+    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/biblio.json')
   ]).then(async results => {
-    let json = Object.assign(results[0].data, results[1].data, results[2].data);
+    let json = Object.assign(
+      results[0].data,// IETF
+      results[1].data,// W3C
+      results[2].data,// WHATWG
+      results[3].data// Biblio
+    );
     return fs.outputFile(compileLocation + '/refs.json', JSON.stringify(json));
   }).catch(e => console.log(e));
 }

package/index.js

@@ -20,6 +20,8 @@ module.exports = async function (options = {}) {
     const { createTermIndex } = require('./src/create-term-index.js');
     createTermIndex();
 
+    const { processWithEscapes } = require('./src/escape-handler.js');
+
     const { insertTermIndex } = require('./src/insert-term-index.js');
     insertTermIndex();
 
@@ -35,6 +37,7 @@ module.exports = async function (options = {}) {
     createVersionsIndex(config.specs[0].output_path);
 
     const { fixMarkdownFiles } = require('./src/fix-markdown-files.js');
+    const { processEscapedTags, restoreEscapedTags } = require('./src/escape-mechanism.js');
 
     let template = fs.readFileSync(path.join(modulePath, 'templates/template.html'), 'utf8');
     let assets = fs.readJsonSync(modulePath + '/config/asset-map.json');
@@ -181,14 +184,7 @@ 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.
        * 
@@ -244,13 +240,16 @@ module.exports = async function (options = {}) {
      * @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));
-        if (replacer) {
-          let argsArray = args ? args.trim().split(replacerArgsRegex) : [];
-          return replacer.transform(match, type, ...argsArray);
-        }
-        return match;
+      // Use the escape handler for three-phase processing
+      return processWithEscapes(doc, function(content) {
+        return content.replace(replacerRegex, function (match, type, args) {
+          let replacer = replacers.find(r => type.trim().match(r.test));
+          if (replacer) {
+            let argsArray = args ? args.trim().split(replacerArgsRegex) : [];
+            return replacer.transform(match, type, ...argsArray);
+          }
+          return match;
+        });
       });
     }
 
@@ -528,7 +527,12 @@ module.exports = async function (options = {}) {
 
         let doc = docs.join("\n");
 
-        // `doc` is markdown 
+        // 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"](katexRules);
@@ -542,6 +546,10 @@ module.exports = async function (options = {}) {
         // 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);
+
         // Process external references to ensure they are inserted as raw HTML, not as JSON string
         const externalReferencesHtml = Array.isArray(externalReferences) 
           ? externalReferences.join('') 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {

package/src/collect-external-references.js

@@ -270,13 +270,17 @@ function processExternalReferences(config, GITHUB_API_TOKEN, options) {
  * 
  * @description
  * This function performs several key operations:
- * 1. Validates GitHub PAT availability and external repository configurations
+ * 1. Optionally uses GitHub PAT for better API performance and higher rate limits
  * 2. Checks validity of repository URLs
  * 3. Extracts xref/tref patterns from markdown content
  * 4. Extends references with repository metadata
  * 5. Processes references to fetch commit information
  * 6. Generates output files in both JS and JSON formats
  * 
+ * Note: The function will run without a GitHub token but may encounter rate limits.
+ * For better performance, provide a GitHub Personal Access Token via environment
+ * variable or the options parameter.
+ * 
  * @example
  * // Basic usage
  * collectExternalReferences();
@@ -289,17 +293,6 @@ function collectExternalReferences(options = {}) {
     const externalSpecsRepos = config.specs[0].external_specs;
     const GITHUB_API_TOKEN = options.pat || process.env.GITHUB_API_TOKEN;
 
-    const explanationPAT =
-`❌ No GitHub Personal Access Token (PAT) was found.
-
-   GitHub requires you to set up a PAT to retrieve external references.
-
-   There is no point in continuing without a PAT, so we stop here.
-
-   Find instructions on how to get a PAT at https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token
-
- `;
-
     const explanationNoExternalReferences =
 `❌ No external references were found in the specs.json file.
 
@@ -310,19 +303,13 @@ function collectExternalReferences(options = {}) {
 `;
     
     // First do some checks
-
-    // Do not run the script if the GitHub API token is not set
+    // Show informational message if no token is available
     if (!GITHUB_API_TOKEN) {
-        console.log(explanationPAT);
-        const userInput = readlineSync.question('ℹ️ Press any key');
-
-        // React to user pressing any key
-        if (userInput.trim() !== '') {
-            console.log('ℹ️ Stopping...');
-            return;
-        }
+        console.log('ℹ️ No GitHub Personal Access Token (PAT) found. Running without authentication (may hit rate limits).');
+        console.log('💡 For better performance, set up a PAT: https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token\n');
     }
-    else if (externalSpecsRepos.length === 0) {
+
+    if (externalSpecsRepos.length === 0) {
         // Check if the URLs for the external specs repositories are valid, and prompt the user to abort if they are not.
         console.log(explanationNoExternalReferences);
         const userInput = readlineSync.question('Press any key');

package/src/escape-handler.js

@@ -0,0 +1,67 @@
+/**
+ * Escape handler for substitution tags in Spec-Up
+ * Provides mechanism to display literal [[tag]] syntax without processing
+ * 
+ * Implements a three-phase approach:
+ * 1. Pre-processing: Convert escaped sequences to temporary placeholders
+ * 2. Tag Processing: Existing substitution logic runs normally (placeholders ignored)
+ * 3. Post-processing: Restore escaped sequences as literals
+ */
+
+const ESCAPED_PLACEHOLDER = '__SPEC_UP_ESCAPED_TAG__';
+
+/**
+ * Pre-processes text to handle escaped substitution tags
+ * @param {string} text - Input text with potential escaped tags
+ * @returns {string} Text with escaped tags replaced by placeholders
+ */
+function preProcessEscapes(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+  
+  // Handle double backslash first: \\[[ → \__PLACEHOLDER__
+  let processed = text.replace(/\\\\(\[\[)/g, `\\${ESCAPED_PLACEHOLDER}`);
+  
+  // Handle single backslash: \[[ → __PLACEHOLDER__
+  processed = processed.replace(/\\(\[\[)/g, ESCAPED_PLACEHOLDER);
+  
+  return processed;
+}
+
+/**
+ * Post-processes text to restore escaped tags as literals
+ * @param {string} text - Text after substitution processing
+ * @returns {string} Text with placeholders restored to literal tags
+ */
+function postProcessEscapes(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+  
+  // Restore placeholders to literal [[
+  return text.replace(new RegExp(ESCAPED_PLACEHOLDER, 'g'), '[[');
+}
+
+/**
+ * Main processing function that wraps existing substitution logic
+ * @param {string} content - Raw markdown content
+ * @param {Function} processSubstitutions - Existing substitution processor
+ * @returns {string} Processed content with escape handling
+ */
+function processWithEscapes(content, processSubstitutions) {
+  if (!content || typeof content !== 'string') {
+    return content;
+  }
+  
+  const preProcessed = preProcessEscapes(content);
+  const substituted = processSubstitutions(preProcessed);
+  return postProcessEscapes(substituted);
+}
+
+module.exports = {
+  preProcessEscapes,
+  postProcessEscapes,
+  processWithEscapes,
+  ESCAPED_PLACEHOLDER
+};

package/src/escape-mechanism.js

@@ -0,0 +1,57 @@
+/**
+ * Escape Mechanism Module for Spec-Up Substitution Tags
+ * 
+ * This module provides functions to handle backslash escape sequences for substitution tags,
+ * allowing users to display tag syntax literally in their documentation.
+ * 
+ * The escape mechanism works in three phases:
+ * 1. Pre-processing: Convert escaped sequences to temporary placeholders
+ * 2. Tag processing: Normal substitution logic (handled elsewhere)
+ * 3. Post-processing: Restore escaped sequences as literals
+ * 
+ * Supported escape pattern:
+ * - \[[tag: content]] → displays as literal [[tag: content]]
+ * 
+ * @version 1.0.0
+ */
+
+/**
+ * Handles backslash escape mechanism for substitution tags
+ * 
+ * Use backslash escape sequences to allow literal [[ tags in markdown
+ * 
+ * Phase 1: Pre-processing - Convert escaped sequences to temporary placeholders
+ * 
+ * @param {string} doc - The markdown document to process
+ * @returns {string} - Document with escaped sequences converted to placeholders
+ */
+function processEscapedTags(doc) {
+  // Replace \[[ with escape placeholder for literal display
+  // In markdown: \[[def: term]] should become [[def: term]] (literal tag syntax)
+  doc = doc.replace(/\\(\[\[)/g, '__SPEC_UP_ESCAPED_TAG__');
+  
+  return doc;
+}
+
+/**
+ * Handles backslash escape mechanism for substitution tags
+ * 
+ * Use backslash escape sequences to allow literal [[ tags in markdown
+ * 
+ * Phase 3: Post-processing - Restore escaped sequences as literals
+ * Converts placeholders back to literal [[ characters
+ * 
+ * @param {string} renderedHtml - The rendered HTML to process
+ * @returns {string} - HTML with placeholders restored to literal [[ tags
+ */
+function restoreEscapedTags(renderedHtml) {
+  // Replace escaped tag placeholders with literal [[ 
+  renderedHtml = renderedHtml.replace(/__SPEC_UP_ESCAPED_TAG__/g, '[[');
+  
+  return renderedHtml;
+}
+
+module.exports = {
+  processEscapedTags,
+  restoreEscapedTags
+};