Template Syntax Documentation

warning

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

This document provides comprehensive documentation for the terminology templates and specification references used in Spec-Up-T, an enhanced version of Spec-Up that adds terminology tooling capabilities.

Overview

Spec-Up-T uses a double-bracket template syntax [[template-type:arguments]] to handle term definitions, references, and cross-specification linking. These templates are processed during the markdown-to-HTML conversion and enable sophisticated terminology management across multiple specifications.

Terminology Templates

1. Definition Template: [[def:term]]

Purpose: Defines a new term and creates an anchor for referencing.

Syntax:

[[def: primary-term, synonym1, synonym2, ...]]

Description:

• Creates a definition term with multiple synonyms
• Generates HTML anchor IDs for each synonym
• Must be the first line of a term definition file
• Followed by the definition content using ~ prefix

Example:

[[def: term 1, term one, Term One]]

~ Lorem ipsum dolor sit amet, consectetur adipiscing elit. This is the definition of the term.

~ Additional paragraphs of the definition can be added with ~ prefix.

Rendered Output:

• Creates <span id="term:term-1">, <span id="term:term-one">, <span id="term:term-one"> anchors
• Generates proper HTML definition list structure
• All synonyms become searchable and referenceable

Implementation Details:

• Spaces in terms are converted to hyphens and lowercased for IDs
• The primary term (first one) is used as the display name
• All synonyms are indexed and can be referenced

2. Reference Template: [[ref:term]]

Purpose: Creates a clickable link to a locally defined term.

Syntax:

[[ref: term-name]]

Description:

• Links to terms defined within the same specification
• Case-insensitive matching
• Generates internal anchor links

Example:

This concept relates to [[ref: term 1]] and [[ref: Term Two]].

Rendered Output:

<a class="term-reference" href="#term:term-1">term 1</a>
<a class="term-reference" href="#term:term-two">Term Two</a>

Features:

• Automatic validation of reference targets
• Warns about unresolved references during build
• Supports all synonyms defined in [[def:]] tags

3. External Cross-Reference Template: [[xref:spec,term]]

Purpose: Creates a link to a term defined in an external specification.

Syntax:

[[xref: external-spec-name, term-name]]

Description:

• Links to terms in other specifications
• Requires external specification to be configured in specs.json
• Opens in external site when clicked

Example:

See the [[xref: test-1, authentication]] concept in the external specification.

Configuration Required:

External specifications must be defined in specs.json:

{
  "specs": [
    {
      "external_specs": [
        {
          "external_spec": "test-1",
          "path": "https://github.com/org/repo",
          "terms_dir": "spec/terms-definitions",
          "gh_page": "https://example.github.io/spec-1/"
        }
      ]
    }
  ]
}

Rendered Output:

<a class="x-term-reference term-reference" 
   data-local-href="#term:test-1:authentication"
   href="https://example.github.io/spec-1/#term:authentication">
   authentication
</a>

Features:

• Dual-mode linking (local and external)
• Fallback to '#' if external spec not configured
• Validation during build process

4. Transcluded Reference Template: [[tref:spec,term]]

Purpose: Embeds the full definition of a term from an external specification.

Syntax:

[[tref: external-spec-name, term-name]]

Description:

• Fetches and displays the complete definition from external repository
• Creates a collapsible definition section
• Shows metadata about the source (repository, commit hash, etc.)
• Must be used as the first line of a term definition file

Example:

[[tref: test-1, digital-signature]]

File Structure:

• Each [[tref:]] should be in its own .md file
• File should contain only the tref tag (no additional content)
• Placed in the terms-definitions directory

Rendered Output:

• Creates a definition term with transcluded content
• Includes metadata table showing source repository information
• Content is fetched from external GitHub repositories
• Supports collapsible/expandable interface

Technical Implementation:

• Fetches latest commit hash from external repository
• Caches content locally for performance
• Validates external specification configuration
• Handles missing terms gracefully

Features:

• Real-time content from external sources
• Metadata tracking (owner, repo, commit hash)
• Collapsible interface for better UX
• Error handling for missing terms

5. File Inclusion Template: [[insert:file.txt]]

Purpose: Includes the content of another file directly into the current document.

Syntax:

[[insert: path/to/file.txt]]

Description:

• Embeds content from external files during build process
• Useful for sharing common content across multiple documents
• Supports relative paths from the current document location

Example:

[[insert: shared-content/common-disclaimer.md]]

Features:

• File content is inserted at build time
• Supports any text-based file format
• Path resolution relative to current document

Additional Template Features

Table-defined Terms

Terms can also be defined within table structures for attribute-based definitions:

Variable            | Default Value  | Max Value
------------------- | -------------  | ---------
[[def: Variable 1]] | 123            | 9999

Features:

• First column definitions automatically create term anchors
• Hovering shows tooltip with entire row context
• Useful for parameter/configuration documentation

Specification References

1. Specification Reference: [[spec:name]]

Purpose: References a complete specification document.

Syntax:

[[spec: specification-name]]

Description:

• Creates a formal reference to an entire specification
• Used in bibliography or reference sections
• Links to the specification's main page

Example:

This document follows the guidelines outlined in [[spec: RFC-3986]].

Features:

• Formal citation formatting
• Automatic link generation
• Bibliography integration

2. Draft Specification Reference: [[spec-draft:name]]

Purpose: References a draft or work-in-progress specification.

Syntax:

[[spec-draft: specification-name]]

Description:

• Similar to [[spec:]] but indicates draft status
• Often used for referencing specifications under development
• May include different styling to indicate draft status

Example:

The proposed changes are detailed in [[spec-draft: new-authentication-protocol]].

Configuration and Setup

External Specifications Configuration

External specifications must be configured in the specs.json file:

{
  "specs": [
    {
      "external_specs": [
        {
          "external_spec": "short-name",
          "path": "https://github.com/organization/spec-name",
          "terms_dir": "spec/terms-definitions",
          "gh_page": "https://organization.github.io/spec-name/"
        }
      ]
    }
  ]
}

Configuration Fields:

• external_spec: Short identifier used in templates
• path: GitHub repository URL
• terms_dir: Directory containing term definition files
• gh_page: URL to the published specification

Term Definition File Structure

Term definition files follow a specific structure:

[[def: primary-term, synonym1, synonym2]]

~ First paragraph of definition with ~ prefix.

~ Additional paragraphs also with ~ prefix.

~ Cross-references: [[ref: other-term]], [[xref: external-spec, external-term]]

Processing Pipeline

1. Pre-processing: Escape mechanism handles literal template syntax with backslash
2. Template Processing: Templates are converted to HTML using markdown-it extensions
3. Markdown Rendering: Standard markdown processing with custom plugins
4. Post-processing: Definition list structure fixes and sorting
5. External Content: Transcluded content is fetched and inserted client-side

Error Handling and Validation

Validation Features

• Reference Validation: Checks for unresolved [[ref:]] links
• External Spec Validation: Verifies external specification configuration
• Term Existence Validation: Confirms transcluded terms exist in external repositories
• Health Checks: Built-in health check system for terminology integrity

Common Error Messages

• "Unresolved References": Terms referenced but not defined
• "Dangling Definitions": Terms defined but never referenced
• "Invalid external spec reference": External specification not configured
• "Term not found in external repository": Transcluded term doesn't exist

Best Practices

1. Naming Conventions:

   • Use lowercase with hyphens for term IDs
   • Provide meaningful synonyms in [[def:]] tags
   • Keep external spec names short and descriptive

2. File Organization:

   • One term per file in terms-definitions directory
   • Use descriptive filenames matching the primary term
   • Group related terms in subdirectories if needed

3. Cross-References:

   • Use [[ref:]] for internal terms
   • Use [[xref:]] for external terms you want to link to
   • Use [[tref:]] for external terms you want to embed

4. External Specifications:

   • Always configure external specs in specs.json
   • Use path for repository URLs and gh_page for published URLs
   • Ensure terms_dir paths are correct

5. Content Guidelines:

   • Start definition content with ~ prefix
   • Use consistent formatting across all terms
   • Include relevant cross-references in definitions

6. File Organization Notes:

   • Term files are automatically detected and indexed (no manual configuration needed)
   • Files are processed in alphabetical order by default
   • Use descriptive filenames that match primary terms

Advanced Features

Escape Mechanism

To display literal template syntax without processing, use a backslash before the opening brackets:

Use \[[def: literal-example]] to show the syntax literally.
Use \[[xref: spec, term]] to display xref syntax.
Use \[[tref: spec, term]] to display tref syntax.

Supported Tag Types: All template types support escaping: def, ref, xref, tref, spec, insert

Automatic Term Detection

• Term files are automatically discovered in the terms-definitions directory
• No manual configuration required (unlike original Spec-Up)
• Files are indexed and processed automatically during build

Performance Optimizations

• Client-side rendering for transcluded content
• Caching of external repository data
• Batch DOM updates for better rendering performance
• Lazy loading of complex definitions

Health Check System

Built-in validation system that checks for:

• Unresolved [[ref:]] references
• Missing external specification configurations
• Invalid [[tref:]] targets
• Dangling definitions (defined but never referenced)

Cognitive Complexity Management

The system is designed to keep cognitive complexity below 15 for maintainability and follows SonarQube analysis standards.

Advanced Performance Features

• Client-side rendering for transcluded content
• Batch DOM updates for better rendering performance
• Caching of external content
• Lazy loading of transcluded definitions

This documentation covers the complete template syntax system used in Spec-Up-T for terminology management and cross-specification linking. The system provides a powerful yet simple way to maintain consistent terminology across multiple related specifications.