ITI MD → HTML

Converts any ITI .md file to a WordPress-embeddable HTML fragment using the shared iti_md_to_html.py converter. Output uses the .iti-showcase CSS class — no , , or tags. Paste directly into a WordPress block or custom HTML template.

Quick commands

Single file → sibling .html (most common):

python3 ~/Cursor/ITI/operations/tools/convert_one_md_to_html.py path/to/file.md

Output is written to path/to/file.html (same directory, same name).

Dry run (verify without writing):

python3 ~/Cursor/ITI/operations/tools/convert_one_md_to_html.py path/to/file.md --dry-run

All Claude Skills → documentation/manual/skills/:

python3 ~/Cursor/ITI/operations/tools/export_claude_skills_html.py

Writes .html for every Claude-Skills//SKILL.md to operations/documentation/manual/skills/.

From Python (inline, no subprocess):

from pathlib import Path
import sys
sys.path.insert(0, str(Path("~/Cursor/ITI/operations/tools").expanduser()))
from iti_md_to_html import convert_md_to_html, wrap_iti_showcase

src = Path("path/to/file.md")
out = src.with_suffix(".html")                          # sibling output
out.write_text(wrap_iti_showcase(convert_md_to_html(src.read_text())))

Skills-dir output (non-sibling destination, e.g. a new skill):

out = Path("~/Cursor/ITI/operations/documentation/manual/skills/my-skill.html").expanduser()
out.write_text(wrap_iti_showcase(convert_md_to_html(src.read_text())))

Output location conventions

What the converter handles

 (HTML-escaped)

What the converter does NOT handle

• • Nested lists (renders flat — restructure source if nesting is needed)

• • Images (!alt) — strip before converting or write HTML manually

• • Raw HTML passthrough — angle brackets inside code blocks are escaped; outside they are not parsed

• • Footnotes, definition lists, or other extended Markdown syntax

• • Files larger than 2 MB (ITI_MD_MAX_BYTES env var controls this limit)

Checking staleness

To check whether an HTML file is out of date with its source:

# True if the .md is newer than its .html companion
[ path/to/file.md -nt path/to/file.html ] && echo "STALE" || echo "current"

AUT-01 (aut01_skill_sync.py) detects stale skill HTML for the skills export target. There is no automatic stale-check for product doc siblings — run it manually after editing .md files.

When to write HTML manually instead

Use the converter for 95 % of cases. Write HTML by hand when:

• The page needs custom components not in the .iti-showcase palette (e.g. .example-block, .toggle-badge added for iti-compress.html)
• The source is not Markdown (e.g. a JSON data file rendered into a table)
• The output needs to embed JavaScript or iframes

When writing manually, always start from the standard STYLE_BLOCK in operations/tools/iti_md_to_html.py and wrap content in