TDML Guide

TDML (TaskManSync Decorator Markup Language) is TaskManSync’s markup for styling Decoration text. It describes presentation; it is not HTML, Markdown, CSS, or a programming language.

For the complete property list, see the TDML Reference. For working source and practical examples, see TDML Examples.

Choose a format

Static Decorations are not bound to the task or window beside them. TDML has no variables, conditionals, interpolation, task/window fields, or built-in access to current task state. Scripted Decorations can build changing text from values available to their Lua runtime, but the dynamic behavior comes from Lua, not TDML syntax. See Scripted Decorations for the available API.

TDML cannot execute code, access files or TaskManSync APIs, load images or hyperlinks, or provide HTML, CSS, JavaScript, QML, general graphics, a canvas, or animation effects. It also has no font-family selector. Use Lua for programmable behavior and the separate Scripted Decoration graphics features for supported drawing.

Create a TDML Decoration

In TaskManSync Settings > Decorations, choose + New > TDML. Select the definition to edit its source and see the preview. The preview reports parser errors and warnings; ordinary pending definition changes use the Settings page’s normal save action. See Creating and Editing Decorations for the full workflow.

Name a Static Decoration

A Static TDML Decoration is named by an optional metadata header at the top of its source, not by TDML syntax:

--[[ Name: Build Status ]]
{fgc:#F8FAFC;bld}BUILD 42{}

The header is not displayed and is not TDML. Without a Name, the Decoration has no name.

The header can also carry the settings TDML supports: WidthMode, Width, Taskbars, and Orientation. FontSize is not a TDML header key; set text size with TDML markup instead, for example {size:30}Large text{}, {sz:14}Small text{}, or {sza:18}Explicitly absolute{} (see the TDML Reference). Importing a .tdml file applies its header; typing or pasting a header into the editor only sets the name when you save. See Importing and Exporting.

Scripted Decoration names use the separate Lua metadata described in the Scripted Decoration guide. Scripted TDML (the decoration.text string) has no header.

Basic syntax

Text-formatting tags use braces. A colon separates a property from its value; semicolons separate properties in one tag; commas separate parameters. An empty tag, {}, closes the most recently opened text-formatting scope and restores the surrounding style.

{fgc:#F8FAFC;bld}Ready {ita}now{}!{}

Formatting scopes can be nested. Properties are inherited into nested scopes until a closing {} restores the previous style. A scope left open at the end of the source is implicitly closed. An unmatched closing {} produces a diagnostic and does not begin a scope.

Property names start with a lowercase ASCII letter and may contain lowercase letters, digits, hyphens, and underscores. Uppercase names are invalid. TDML has no quoted-string syntax: quotes are ordinary characters, not delimiters. Whitespace around :, ;, and , inside a tag is ignored; whitespace in text is preserved.

An empty property or parameter is invalid, so do not leave a tag ending in ; or a parameter list with an extra comma. The invalid property is ignored while other valid properties continue to apply.

A backslash escapes the next character. This lets braces and separators appear literally; the examples show the spelling and result.

Decoration directives such as dcolor, posh, and posv are different from text-formatting scopes. They apply to the whole Decoration presentation, are valid only at root scope, and do not require a closing {} when the tag contains directives only. A directive-only tag consumes one immediately following line ending (LF, CRLF, or CR). Any additional line ending remains text. A line ending after a tag that also opens a formatting scope is ordinary text. See Whole-Decoration directives.

Invalid input and limits

Invalid properties or parameters produce diagnostics; the invalid property is ignored while other valid properties and text continue. Unknown, structurally valid properties are ignored. Fatal input, such as an unterminated tag or an unescaped opening brace inside a tag, prevents styled parsing.

For a Static Decoration, fatal input is shown as literal presentation text and the preview retains the diagnostics. A leading metadata header is still omitted. For Scripted Decorations, the exact source string becomes literal presentation text and its parse diagnostics are retained with the Scripted presentation. This keeps malformed markup visible rather than dropping the text.

Parser safeguards that may matter for very large or generated text are:

These limits are rarely reached in ordinary Decorations. More detail about what each property accepts is in the reference.

Unicode

TDML text supports Unicode directly, including emoji. No special syntax is needed. Escaping still applies to TDML’s structural characters, not to ordinary Unicode text.

Layout and related guides

TDML styles text within a Decoration; it does not set the Decoration’s Content, Fixed, or Flexible width and does not move the Decoration in the shared workspace. posh and posv position the complete TDML presentation relative to its Decoration surface; the surface clips content that extends beyond it.

The Decoration’s Width is configured separately and follows the taskbar’s item flow: horizontal on a horizontal taskbar, vertical on a vertical taskbar. The taskbar determines the placed orientation; the Orientation control in Settings changes only the preview. Relative szr sizing uses the Decoration’s realized internal height. See Decoration Width and Placing Decorations.

For color fallback and the difference between text-run and surface colors, see Colors and Appearance. For other Decoration formats, see Text and TDML.