Skip to main content

Inside index.html

This document provides a comprehensive inventory of what is stored in the final index.html file generated by Spec-Up-T.

HTML Structure Overview​

The index.html file is a complete single-page application (SPA) that contains a technical specification document with interactive features. It's based on Bootstrap 5.3 and includes extensive JavaScript functionality.

Template Variables Interpolated​

The following variables are interpolated into the HTML template during the build process:

Basic Metadata​

  • ${title} - Document title from spec configuration
  • ${description} - Document description from spec configuration
  • ${author} - Document author from spec configuration
  • ${specFavicon} - Path to favicon file
  • ${specLogo} - Path to specification logo
  • ${specLogoLink} - Link associated with the logo

Content Sections​

  • ${toc} - Generated table of contents HTML
  • ${render} - Main specification content rendered from markdown files
  • ${externalReferences} - HTML content for external specification references
  • ${externalSpecsList} - List of external specifications in the sidebar

Assets and Resources​

  • ${assetsHead} - CSS and JavaScript files for the document head
  • ${assetsBody} - JavaScript files for the document body
  • ${assetsSvg} - SVG icon definitions
  • ${xtrefsData} - External cross-reference data as embedded JavaScript

Configuration Data​

  • ${features} - Space-separated list of enabled features
  • ${spec} - Complete specification configuration as JSON string

Embedded JavaScript Variables​

Primary Configuration Object​

window.specConfig = ${spec}

This contains the complete specification configuration as a JavaScript object, including:

  • Specification metadata (title, description, author)
  • File paths and directory structure
  • External specifications configuration
  • Asset definitions
  • Feature flags
  • Output paths

External Cross-References Data​

The ${xtrefsData} variable contains a <script> tag with external term reference data loaded from .cache/xtrefs-data.js if it exists. This enables cross-specification term linking.

HTML Structure Components​

Head Section​

  • Meta tags for charset, viewport, description, author
  • Bootstrap Icons CDN link
  • Custom CSS (either linked files in dev mode or inlined compiled CSS)
  • Custom JavaScript for head section
  • KaTeX support (if enabled)

Body Structure​

  1. Header Navigation

    • Dark/light theme toggle
    • Container width toggle
    • Font size adjustment controls
    • Settings and issues panels

  2. Main Layout

    • Responsive sidebar with table of contents
    • Main content area with rendered specification
    • Terminology section utility container

  3. Off-canvas Panels

    • Issues panel (GitHub integration)
    • Settings panel with external specifications list

  4. Footer Scripts

    • Chart.js library for data visualization
    • Custom application JavaScript
    • Bootstrap functionality

Interactive Features​

JavaScript Functionality​

The embedded JavaScript provides:

  • Theme switching (dark/light mode)
  • Responsive layout controls
  • Font size adjustment
  • Search functionality within the document
  • Term filtering and alphabetical indexing
  • Collapsible sections
  • PDF download capabilities
  • GitHub integration for issues
  • External specification linking
  • Terminology cross-referencing
  • Modal dialogs
  • Clipboard functionality for anchor links

CSS Styling​

  • Bootstrap 5.3 framework
  • Custom specification styling
  • Print-specific styles
  • Theme-aware color schemes
  • Responsive design breakpoints

Data Storage Mechanisms​

1. Template Interpolation​

Static data is embedded during build time through string replacement in the HTML template.

2. JavaScript Objects​

Dynamic configuration and state data is stored in global JavaScript objects:

  • window.specConfig - Main configuration object
  • External reference data objects (if present)

3. HTML Data Attributes​

Feature flags and configuration options are stored as HTML data attributes on elements.

4. Local Storage Integration​

The JavaScript code may use browser local storage for:

  • User preferences (theme, font size, layout width)
  • GitHub tokens for API access
  • Search history and filters

File Dependencies​

The index.html references or embeds:

  • Compiled CSS from assets/compiled/head.css
  • Compiled JavaScript from assets/compiled/head.js and assets/compiled/body.js
  • SVG icons from assets/icons.svg
  • External fonts (KaTeX fonts if math support is enabled)
  • Bootstrap Icons from CDN
  • Chart.js library from CDN

Purpose and Rationale​

This file structure exists because:

  1. Self-contained Distribution: Creates a single file that contains everything needed to view the specification
  2. Offline Capability: All resources are embedded or available locally
  3. Interactive Documentation: Provides rich user interface features beyond static HTML
  4. Cross-reference Support: Enables linking between different specifications
  5. Professional Presentation: Offers publication-quality output with advanced features
  6. Accessibility: Includes proper semantic markup and accessibility features
  7. Responsive Design: Works across different devices and screen sizes

The file should be retained as it represents the final, complete specification document that can be distributed, hosted, or archived independently.