templatedata-from-readme

name: templatedata-from-readme description: Convert a Markdown Parameters table in a wiki template README to a `<templatedata>` JSON block ready for embedding on a Template namespace doc page. Use when deploying a Template:* page's README to its /doc subpage (called by deploy-to-wiki), or when the user asks to "generate templatedata" / "preview templatedata" for a README.

Pure transformation skill: takes a README.md following the wiki-tools template-doc convention and returns a <templatedata> block that mirrors the Parameters table.

When to invoke

Deploy pipeline for a Template:*/doc page — deploy-to-wiki delegates to this skill.
Ad-hoc preview: user wants to see the TemplateData JSON before deploy.
Pre-commit validation: catch malformed Parameters tables before they break the wiki.

Input format

A README.md following the wiki-tools convention. The Parameters table can be 6 columns (Label is derived from Name) or 7 columns (Label provided explicitly). The skill detects column count from the header row.

6-column form (default):

# Template:Foo/Bar

One-paragraph intro describing what the template renders. This becomes
the TemplateData top-level `description`.

## Usage
...

## Parameters

| Name | Type | Required | Default | Description | Example |
|------|------|----------|---------|-------------|---------|
| `paramA` | string | Yes |  | Brief desc. | `value` |
| `paramB` | number | No | `0` | Another desc. | `42` |
| `paramC` | string | No | (falls back to lookup) | Optional with prose default. | `xyz` |

## Behavior
...

7-column form (explicit Label, useful for acronyms/abbreviations):

| Name | Label | Type | Required | Default | Description | Example |
|------|-------|------|----------|---------|-------------|---------|
| `uuid` | UUID | string | No | (falls back to SMW) | Entity UUID. | `80ee3b95-...` |
| `paramB` | Param B | number | No | `0` | Another desc. | `42` |

Output format

A wikitext block:

<templatedata>
{
    "description": "<intro paragraph text>",
    "params": {
        "paramA": { "label": "ParamA", "description": "Brief desc.", "type": "string", "required": true, "example": "value" },
        "paramB": { "label": "ParamB", "description": "Another desc.", "type": "number", "required": false, "default": "0", "example": "42" },
        "paramC": { "label": "ParamC", "description": "Optional with prose default.", "type": "string", "required": false, "example": "xyz" }
    },
    "paramOrder": ["paramA", "paramB", "paramC"],
    "format": "inline"
}
</templatedata>

Conversion rules

Column indices below assume the 6-column form. For the 7-column form, shift Type/Required/Default/Description/Example one cell right and read Label from cell 2.

README cell	TemplateData field	Rule
Name	key in `params`	Strip backticks. Used verbatim.
Label (optional, 7-col only)	`label`	Use the cell value as-is (preserves acronym casing like "UUID").
Type	`type`	Lowercase. Validate against vocabulary (see below). Fall back to `unknown` and warn if unrecognized.
Required	`required`	`Yes` / `Y` / `true` → `true`; everything else → `false`.
Default	`default`	Wrapped in parens (e.g. `(falls back to ...)`) → prose, omit from JSON. Wrapped in backticks → strip and use as string. Empty cell → omit.
Description	`description`	Plain string. Strip surrounding whitespace.
Example	`example`	Strip backticks. Empty cell → omit.
Top-level	`description`	First paragraph after the H1 title. Strip link syntax to plain text — both Markdown `[Text](URL)` → `Text` and wikitext `[[Page\|Text]]` → `Text`, `[[Page]]` → `Page`. TemplateData descriptions are rendered as plain text by VisualEditor; link syntax leaks through ugly.
Top-level	`paramOrder`	Order of rows in the table.
Top-level	`format`	Default `inline`. Override via HTML comment in the README: `<!-- templatedata: format=block -->`.
Derived `label` (6-col only)	`label`	Name with first letter capitalized; underscores replaced with spaces. For acronyms or other custom labels, use the 7-column form.

Type vocabulary

Validated against MediaWiki's TemplateData type list:

string, number, boolean, wiki-page-name, wiki-user-name, wiki-template-name, wiki-file-name, date, url, line, unbalanced-wikitext, content, unknown.

Unrecognized types fall back to unknown with a warning printed to the user.

Process

Locate the H1 title (first # ... line). Everything after it up to the next blank line is the top-level description.
Find the Parameters section — heading ## Parameters followed by a Markdown table. If absent, return nil and tell the caller (the template has no params; the caller decides whether to omit the block or report an error).
Parse the table — header row, separator (|---|---|...), then body rows. Detect form by the header: Name | Type | Required | Default | Description | Example is 6-column; Name | Label | Type | Required | Default | Description | Example is 7-column. Reject other shapes — halt with an error pointing at the offending row.
Apply the conversion rules above to each row.
Look for HTML comment overrides anywhere in the README:
-  → format: "block"
-  → format: "inline"
Emit the block with the JSON pretty-printed and wrapped in <templatedata>...</templatedata>.

Edge cases

No Parameters section → return nil.
Empty table body (header only) → emit <templatedata> with empty params so VisualEditor doesn't show "Unknown template parameters".
Pipe character in cell content must be escaped as \| per CommonMark; the parser must respect that.
Multi-line cell content — Markdown tables don't natively support newlines in cells. Use <br> (HTML) — passes through to TemplateData fine.
Aliases / suggested / autovalue / sets / maps — not supported by the basic 6-column table. Either add escape-hatch HTML comments later, or extend the table when needed. v1 doesn't handle these; report as out-of-scope.

Output discipline

JSON must be valid and parseable. Use a JSON serializer, not string concatenation.
4-space indent for the JSON body (matches existing on-wiki style).
Never inject extra whitespace before <templatedata> or after </templatedata> — callers control surrounding whitespace.

Validation

Before emitting:

All params keys are non-empty after backtick stripping.
All type values are in the vocabulary (or warned-and-coerced to unknown).
paramOrder covers every key in params, in the same order they appeared.
Top-level description is a non-empty string.