Skip to main content

Double Bracket Template Syntax

Updated: 2025-09-28 20:57:48

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 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",
          "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) via data-local-href and href attributes
  • Fallback to '#' if external spec not configured
  • Validation during build process
  • Tooltip support with data-term-content when external definitions are available
  • CSS classes: x-term-reference term-reference for styling

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

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

Syntax:

[[tref: external-spec-name, term-name]]
[[tref: external-spec-name, term-name, alias1]]
[[tref: external-spec-name, term-name, alias1, alias2, ...]]

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
  • Supports multiple aliases (comma-separated after the term name)

Example:

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

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]] (Not Currently Implemented)​

warning

Status: This template is mentioned in test files and regex patterns but is not currently implemented in the template-tag parser. It exists as placeholder functionality that may be added in future versions.

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

Planned Syntax:

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

Note: While this syntax appears in test files and is recognized by regex patterns, attempting to use it will not produce the expected file inclusion behavior.

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
  • Implemented in separate spec-parser.js module
  • Supports grouped references like [[spec-normative:]] and [[spec-informative:]]

Example:

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

Features:

  • Formal citation formatting with [RFC-3986] style links
  • Automatic link generation with #ref: anchors
  • Bibliography integration and grouping
  • Normalizes specification names (uppercase with hyphens)

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",
          "gh_page": "https://organization.github.io/spec-name/"
        }
      ]
    }
  ]
}

Configuration Fields:

  • external_spec: Short identifier used in templates
  • path: GitHub repository URL
  • 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

  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.