T8 Syntax

Overview

T8 Syntax is a markdown-like language for creating rich narrative text visualizations. It extends standard Markdown with special annotations for data entities, making it easy to highlight metrics, trends, and insights in your text.

Why T8 Syntax?

T8 Syntax is designed to be:

Human-readable: Based on Markdown, familiar and easy to learn
LLM-friendly: Can be easily generated by AI models with simple prompts
Data-aware: Built-in support for metric values, percentages, trends, and other data entities
Extensible: Support for custom phrases and blocks

Basic Syntax

T8 Syntax uses standard Markdown for structure and adds special entity annotations using the format:

[display text](entity_type, property=value, ...)

Example

markdown

# Sales Report

Total sales reached [¥1,234,567](metric_value, origin=1234567).

Eastern region contributed [¥800,000](metric_value), 
accounting for [64.8%](contribute_ratio, assessment="positive").

Core Components

T8 Syntax is organized into the following hierarchical structure:

Document
- The top-level container for the entire narrative text
- Can include a headline and multiple sections
- Supports global styling
Section
- Groups related paragraphs together
- Supports standard paragraphs and custom blocks
- Can be extended for different display needs
Paragraph
- Supports multiple types: headings (# to ######), text, lists
- Standard Markdown paragraph syntax
- Can be extended with custom types
Phrase & Entity
- The smallest unit of text
- Plain text or annotated entities
- Entities include metrics, dimensions, trends, etc.

Entity Types

T8's power lies in its rich set of entity types that go beyond standard Markdown. These entities enable you to semantically mark up data in your narrative text, providing visual emphasis and interactive capabilities.

Core Metric Entities

`metric_name`

Introduction: Identifies the name or label of a metric being discussed.

Use Cases:

Introducing key performance indicators (KPIs)
Labeling metrics in explanatory text
Creating glossary-style definitions

Example:

markdown

[Daily Active Users](metric_name) increased significantly this quarter.

`metric_value`

Introduction: Represents the numeric value of a metric, with support for formatting and origin data.

Use Cases:

Displaying KPI values
Showing measurement results
Presenting statistical data

Properties:

origin: The raw numeric value (for calculations)
unit: Optional unit of measurement

Example:

markdown

Total revenue reached [¥1,234,567](metric_value, origin=1234567).
Sales volume was [1.2 billion units](metric_value, origin=1200000000).

`other_metric_value`

Introduction: For secondary or supporting metric values that are not the primary focus.

Use Cases:

Supporting statistics
Contextual metrics
Comparison benchmarks

Example:

markdown

[Average order value](other_metric_value) was [$125](metric_value, origin=125).

Change & Trend Entities

`delta_value`

Introduction: Represents absolute change in a metric value, with positive/negative assessment.

Use Cases:

Showing absolute increases or decreases
Year-over-year comparisons
Sequential period changes

Properties:

origin: The numeric change value
assessment: "positive", "negative", or "equal"

Example:

markdown

Sales increased by [¥180,000](delta_value, origin=180000, assessment="positive").
Revenue decreased by [¥50,000](delta_value, origin=-50000, assessment="negative").

`ratio_value`

Introduction: Represents percentage change or growth rate.

Use Cases:

Growth rates
Percentage changes
Period-over-period comparisons

Properties:

origin: The decimal ratio (e.g., 0.15 for 15%)
assessment: Direction evaluation

Example:

markdown

Revenue grew by [15%](ratio_value, origin=0.15, assessment="positive").
Sales declined [3.2%](ratio_value, origin=-0.032, assessment="negative") year-over-year.

`contribute_ratio`

Introduction: Indicates the contribution percentage of a part to the whole.

Use Cases:

Market share
Contribution analysis
Composition breakdowns

Properties:

origin: The decimal ratio
assessment: Evaluation of the contribution

Example:

markdown

Eastern region accounts for [64.8%](contribute_ratio, origin=0.648, assessment="positive") of total sales.

`proportion`

Introduction: Represents a part-to-whole ratio or fraction.

Use Cases:

Showing fractions
Demographic distributions
Segmentation data

Properties:

origin: The decimal proportion

Example:

markdown

[3 out of 4](proportion, origin=0.75) customers prefer online shopping.

`trend_desc`

Introduction: Qualitative description of a trend or direction.

Use Cases:

Describing movement patterns
Trend characterization
Qualitative assessments

Properties:

assessment: Evaluation of the trend direction

Example:

markdown

The market shows [strong growth](trend_desc, assessment="positive").
Prices remained [stable](trend_desc, assessment="equal").

Dimensional Entities

`dim_value`

Introduction: Represents a dimension value such as category, region, product, or segment.

Use Cases:

Geographic regions
Product categories
Customer segments
Time periods

Example:

markdown

[Asia-Pacific](dim_value) remains the largest market.
[Premium devices](dim_value) showed strong growth.

`time_desc`

Introduction: Temporal references and time period descriptions.

Use Cases:

Date references
Time period labels
Temporal comparisons

Example:

markdown

In [2024](time_desc), global shipments reached new heights.
Results for [Q4 2023](time_desc) exceeded expectations.

Advanced Analytics Entities

`rank`

Introduction: Indicates ranking position with optional detailed ranking data.

Use Cases:

Competitive rankings
Top/bottom performers
Sorted lists

Properties:

detail: Array of values for visualization

Example:

markdown

China [ranked 1st](rank, detail=[320, 180, 90, 65, 45]) globally.

`difference`

Introduction: Highlights the gap or difference between values.

Use Cases:

Comparative analysis
Gap analysis
Distance metrics

Properties:

detail: Array showing the progression

Example:

markdown

The [gap of 140M units](difference, detail=[200, 180, 160, 140]) is narrowing.

`anomaly`

Introduction: Marks unusual patterns or outliers in data.

Use Cases:

Outlier detection
Unusual patterns
Data quality issues

Properties:

detail: Data showing the anomaly

Example:

markdown

We detected [unexpected concentration](anomaly, detail=[15, 18, 20, 65, 22]) in urban areas.

`association`

Introduction: Describes correlations or relationships between variables.

Use Cases:

Correlation analysis
Causal relationships
Dependency patterns

Properties:

detail: Data points showing the association

Example:

markdown

Sales showed [strong correlation](association, detail=[{"x":100,"y":105},{"x":120,"y":128}]) with marketing spend.

`distribution`

Introduction: Represents how data is distributed across categories or ranges.

Use Cases:

Frequency distributions
Category breakdowns
Range analyses

Properties:

detail: Array of distribution values

Example:

markdown

The [distribution](distribution, detail=[15, 25, 35, 15, 10]) shows normal characteristics.

`seasonality`

Introduction: Indicates periodic or seasonal patterns in data.

Use Cases:

Seasonal trends
Cyclical patterns
Periodic variations

Properties:

detail: Object with data and optional range

Example:

markdown

We observed [clear seasonality](seasonality, detail={"data":[80, 90, 95, 135], "range":[0, 150]}) with Q4 peaks.

Complete Example

Here's a comprehensive example using multiple entity types:

markdown

# Q4 Sales Report

## Overview

In [Q4 2024](time_desc), [total revenue](metric_name) reached 
[¥5.2M](metric_value, origin=5200000), representing a 
[¥800K increase](delta_value, origin=800000, assessment="positive") and 
[18% growth](ratio_value, origin=0.18, assessment="positive") compared to Q3.

## Regional Performance

[North America](dim_value) led with [¥2.1M](metric_value, origin=2100000), 
accounting for [40%](contribute_ratio, origin=0.40, assessment="positive") 
of total revenue. The region [ranked 1st](rank, detail=[2100000, 1800000, 1300000]) 
among all markets.

[Europe](dim_value) showed [strong momentum](trend_desc, assessment="positive"), 
with [nearly half](proportion, origin=0.48) of sales from new customers.

See Phrase & Entity for technical implementation details.

Detailed Documentation

Structure - Understand the overall syntax structure
Elements
- Document - Top-level document structure
- Section - Section blocks
- Paragraph - Paragraph types
- Phrase & Entity - Text and entity annotations

T8 Syntax ​

Overview ​

Why T8 Syntax? ​

Basic Syntax ​

Example ​

Core Components ​

Entity Types ​

Core Metric Entities ​

metric_name ​

metric_value ​

other_metric_value ​

Change & Trend Entities ​

delta_value ​

ratio_value ​

contribute_ratio ​

proportion ​

trend_desc ​

Dimensional Entities ​

dim_value ​

time_desc ​

Advanced Analytics Entities ​

rank ​

difference ​

anomaly ​

association ​

distribution ​

seasonality ​

Complete Example ​

Detailed Documentation ​

T8 Syntax

Overview

Why T8 Syntax?

Basic Syntax

Example

Core Components

Entity Types

Core Metric Entities

`metric_name`

`metric_value`

`other_metric_value`

Change & Trend Entities

`delta_value`

`ratio_value`

`contribute_ratio`

`proportion`

`trend_desc`

Dimensional Entities

`dim_value`

`time_desc`

Advanced Analytics Entities

`rank`

`difference`

`anomaly`

`association`

`distribution`

`seasonality`

Complete Example

Detailed Documentation