Skip to main content

Markdown-it Code

warning

This documentation was generated by Copilot's “Claude Sonnet 4 (Preview)” and has not yet been verified by a human.

Overview​

This document provides a comprehensive overview of all markdown-it code in the Spec-Up-T codebase. Markdown-it is the core parsing engine that converts Markdown text to HTML, with extensive customizations for technical specification authoring.

Architecture Overview​

Processing Pipeline​

Markdown Input
      ↓
1. Pre-processing (escape handling, custom replacers)
      ↓  
2. markdown-it Parsing (tokens creation)
      ↓
3. Plugin Processing (custom extensions)
      ↓
4. Rendering (tokens → HTML)
      ↓
5. Post-processing (definition list fixes, sorting)
      ↓
HTML Output

Core Files​

1. /index.js - Main Processing Engine​

Purpose: Contains the primary markdown-it configuration and rendering pipeline.

Key Components:

markdown-it Instance Configuration​

const md = require('markdown-it')({
  html: true,        // Allow raw HTML tags
  linkify: true,     // Auto-detect URLs  
  typographer: true  // Smart typography
})

Custom Template Processors​

  • Terminology Templates: [[def:term]], [[ref:term]], [[xref:spec,term]], [[tref:spec,term]]
  • Specification References: [[spec:name]], [[spec-draft:name]]

Third-party Plugins​

  • markdown-it-attrs - Add HTML attributes {.class #id}
  • markdown-it-deflist - Definition lists for terminology
  • markdown-it-chart - Chart.js integration
  • markdown-it-katex - Mathematical notation
  • markdown-it-prism - Syntax highlighting
  • markdown-it-toc-and-anchor - Table of contents generation
  • And many others...

Custom Replacer System​

Pre-processes special tags before markdown-it parsing:

  • [[insert:file.txt]] - File inclusion
  • [[tref:spec,term]] - Transcluded term handling

Main Render Function​

The core function that orchestrates the entire markdown-to-HTML transformation:

  1. Load and combine markdown files
  2. Add terminology section markers
  3. Process escaped tags and replacers
  4. Run markdown-it processing (md.render(doc))
  5. Post-process definition lists
  6. Sort terms alphabetically
  7. Generate final HTML page

2. /src/markdown-it-extensions.js - Custom Extensions​

Purpose: Provides specialized markdown-it plugins for Spec-Up-T functionality.

Key Features:

Custom Template System​

  • Parsing Rule: Processes [[tag:args]] syntax during inline parsing
  • Template Tokens: Creates special tokens for custom rendering
  • Escape Handling: Supports \[[tag]] for literal output

Bootstrap Table Integration​

  • Automatically wraps tables in responsive containers
  • Adds Bootstrap CSS classes for styling
  • Handles existing class attributes gracefully
  • Extracts URL path segments
  • Adds path-0, path-1 attributes for CSS targeting
  • Special handling for auto-detected links

Definition List Enhancements​

  • Terminology Section Detection: Identifies main terms list
  • Empty Element Cleanup: Removes broken <dt></dt> elements
  • Visual Grouping: Adds last-dd classes for styling
  • Transcluded Term Support: Handles externally-defined terms

3. /assets/js/declare-markdown-it.js - Client-side Configuration​

Purpose: Initializes markdown-it for browser use.

Configuration:

const md = window.markdownit({
   html: true,        // Allow raw HTML
   linkify: true,     // Auto-detect URLs
   typographer: true  // Smart typography
});

Key Concepts​

Template System​

The template system processes custom syntax like [[tag:args]] to generate dynamic content:

Template Types​

  • [[def:term1,term2]] - Define multiple terms
  • [[ref:term]] - Reference to local term
  • [[xref:spec,term]] - Reference to external specification term
  • [[tref:spec,term]] - Transcluded external term
  • [[spec:name]] - Specification reference
  • [[insert:file.txt]] - File inclusion

Processing Phases​

  1. Detection: Find [[...]] patterns in text
  2. Parsing: Extract type and arguments
  3. Processing: Apply appropriate template handler
  4. Rendering: Generate final HTML output

Definition List Processing​

Critical for terminology sections in technical specifications:

Challenges Addressed​

  • Empty <dt> elements breaking layout
  • Transcluded terms disrupting list structure
  • Visual grouping of definition groups
  • Special styling for terminology sections

Solutions Implemented​

  • Empty element detection and removal
  • Definition list structure repair
  • CSS class injection for styling
  • Transcluded term integration

Escape Mechanism​

Handles literal display of template syntax:

Three-Phase Processing​

  1. Pre-process: Convert \[[tag]] to placeholders
  2. Process: Apply normal template processing (placeholders ignored)
  3. Post-process: Restore placeholders as literal [[tag]]

Integration Points​

With Gulp Build System​

  • /gulpfile.js references markdown-it assets in asset map
  • Compiled versions stored in /assets/compiled/

With External References​

  • Fetches terms from external specifications
  • Integrates with GitHub API for external content
  • Caches external data for performance

With File Processing​

  • Processes multiple markdown files
  • Handles file inclusion via [[insert:...]]
  • Manages terminology file structures

Performance Considerations​

Caching​

  • External reference data cached locally
  • Compiled assets for production builds
  • Minimal re-processing during development

Optimization​

  • Helper functions extracted to reduce complexity
  • Efficient token processing algorithms
  • Minimal DOM manipulation in post-processing

Error Handling​

Validation​

  • Reference validation (all [[ref:...]] have definitions)
  • Template syntax validation
  • External specification availability checking

Graceful Degradation​

  • Unknown template types preserved as-is
  • Missing external references handled gracefully
  • Fallback rendering for failed templates

Development Workflow​

Adding New Template Types​

  1. Add template processor to /index.js
  2. Implement filter and parse/render functions
  3. Add tests in appropriate test files
  4. Update documentation

Modifying Definition List Behavior​

  1. Update helper functions in /src/markdown-it-extensions.js
  2. Test with various terminology structures
  3. Ensure empty element handling works correctly

Debugging Tips​

  • Use console.log in template processors to trace execution
  • Examine token structures in markdown-it debugging
  • Test with escaped templates to verify escape mechanism
  • Check definition list structure in browser developer tools

Best Practices​

Template Design​

  • Keep template syntax simple and intuitive
  • Provide clear error messages for invalid syntax
  • Support both required and optional arguments
  • Document template behavior thoroughly

Performance​

  • Minimize regex operations in hot paths
  • Cache expensive computations
  • Avoid deep token tree traversal when possible
  • Use efficient array/object operations

Maintainability​

  • Extract complex logic into helper functions
  • Add comprehensive comments explaining algorithms
  • Keep cognitive complexity below 15 (SonarQube requirement)
  • Write tests for all template types and edge cases

File Dependencies​

index.js
├── src/markdown-it-extensions.js (custom plugins)
├── src/escape-handler.js (escape mechanism)
├── Third-party markdown-it plugins
└── assets/js/declare-markdown-it.js (client-side)

gulpfile.js
├── config/asset-map.json (references markdown-it assets)
└── assets/compiled/ (built assets)

This documentation should help you understand how markdown-it is used throughout the Spec-Up-T codebase and how the various components work together to process technical specifications.