feat(export-rss,export-ics): render Markdown descriptions to HTML

OTE's `description` field allows Markdown, but both exporters treated it
as plain text. RSS now renders it to HTML in the item body; ICS adds
X-ALT-DESC;FMTTYPE=text/html alongside the unchanged plain-text
DESCRIPTION, since Outlook drops DESCRIPTION once X-ALT-DESC is present.
Raw HTML inside the Markdown source is escaped rather than passed through
live. Also fixes export-rss's reverse-parser (used by apps/preview),
which only read <p> elements and would silently drop Markdown
lists/headings from the description.

Closes #50

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: hhkaos

packages/export-ics/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@opentechevents/export-ics` are documented here.
 
+## 0.3.1
+
+- Added `X-ALT-DESC;FMTTYPE=text/html` — `description` (plain text or
+  Markdown, per the OTE spec) is now rendered to HTML for this de facto
+  rich-text extension (Outlook 2007+, Thunderbird/Lightning), alongside the
+  unchanged plain-text `DESCRIPTION`. Built from the same parts as
+  `DESCRIPTION` (online link, moved-online note, cfp/eligibility/offers),
+  since Outlook ignores `DESCRIPTION` entirely once `X-ALT-DESC` is present.
+  Raw inline/block HTML found in the Markdown source is escaped rather than
+  passed through live.
+
 ## 0.3.0
 
 - Initial package release for OTE spec v0.3.

packages/export-ics/README.md

@@ -28,7 +28,7 @@ usage or I/O error.
 | --- | --- |
 | `id` | `UID` |
 | `name` | `SUMMARY` (`;LANGUAGE=<textLanguage>` when set) |
-| `description` | `DESCRIPTION` (`;LANGUAGE=<textLanguage>` when set) |
+| `description` | `DESCRIPTION` (`;LANGUAGE=<textLanguage>` when set, literal Markdown source) + `X-ALT-DESC;FMTTYPE=text/html` (rendered HTML, see below) |
 | `startDate` / `endDate` + `timezone` | `DTSTART` / `DTEND` (see below) |
 | `url` (else `location.onlineUrl`) | `URL` |
 | `location.venue` | `LOCATION` |
@@ -68,3 +68,17 @@ Decisions worth knowing:
 - **Dropped, not approximated**: `attendanceMode`, `languages`, `license`,
   `source` have no iCal equivalent and are omitted. Absent fields stay absent
   (e.g. no `STATUS` is invented when `status` is missing).
+- **`description` is plain text or Markdown (OTE spec)**, but RFC 5545
+  `DESCRIPTION` is TEXT-only — it can't hold markup. `X-ALT-DESC;FMTTYPE=text/html`
+  is the de facto (non-standard, but widely implemented — Outlook 2007+,
+  Thunderbird/Lightning) extension for a rich-text alternative, so it carries
+  the Markdown rendered to HTML. It's built from the same parts as
+  `DESCRIPTION` (the `Online:`/moved-online note, `cfp`/`eligibility`/`offers`
+  text), not just the description alone: Outlook ignores `DESCRIPTION`
+  entirely once `X-ALT-DESC` is present, so nothing may exist only in one of
+  the two. Raw inline/block HTML found inside the Markdown source is escaped
+  rather than passed through live, so it can't smuggle real markup into a
+  client that renders this fragment. Apple Calendar's support for
+  `X-ALT-DESC` is inconsistent; Google Calendar ignores it and always shows
+  plain-text `DESCRIPTION`, which is why that property always stays
+  populated too.

packages/export-ics/fixtures/feed.json

@@ -102,6 +102,13 @@
       "timezone": "Europe/Madrid",
       "status": "moved-online",
       "location": { "onlineUrl": "https://meet.example/pydata-madrid" }
+    },
+    {
+      "id": "https://mdtest.example/2026-11",
+      "name": "Markdown description test",
+      "description": "**Bold** intro with a [link](https://example.org/info).\n\n<script>alert(1)</script> should not run.",
+      "startDate": "2026-11-03T18:00",
+      "timezone": "Europe/Madrid"
     }
   ]
 }

packages/export-ics/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentechevents/export-ics",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Converts an OTE Feed into an iCalendar (.ics) document",
   "license": "MIT",
   "homepage": "https://github.com/OpenTechEvents/ote-tools/tree/main/packages/export-ics",
@@ -29,7 +29,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@opentechevents/validate": "workspace:*"
+    "@opentechevents/validate": "workspace:*",
+    "marked": "^18.0.9"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

packages/export-ics/src/index.ts

@@ -1,3 +1,5 @@
+import { marked, type Tokens } from "marked";
+
 import type { OteEvent, OteEventStatus, OteFeed, OteOrganizer } from "./types.js";
 
 export type {
@@ -19,6 +21,36 @@ export type {
 const CRLF = "\r\n";
 const encoder = new TextEncoder();
 
+/** Escapes a value for literal display inside an HTML fragment (X-ALT-DESC). */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// `description` is plain text or Markdown (OTE spec). DESCRIPTION (RFC 5545
+// TEXT) can't hold markup, so this is rendered separately into an HTML
+// fragment for X-ALT-DESC;FMTTYPE=text/html — the de facto (non-standard but
+// widely implemented, e.g. Outlook) extension for rich-text VEVENT
+// descriptions. Raw inline/block HTML in the source is escaped rather than
+// passed through live, so it can't smuggle real markup into a client that
+// renders this fragment.
+const descriptionRenderer = new marked.Renderer();
+descriptionRenderer.html = ({ text }: Tokens.HTML | Tokens.Tag) => escapeHtml(text);
+
+/** Renders an OTE `description` (plain text or Markdown) to an HTML fragment. */
+function descriptionToHtml(markdown: string): string {
+  return marked.parse(markdown, {
+    renderer: descriptionRenderer,
+    // A plain-text description is the common case, and a lone newline in one
+    // reads as an intended line break, not two words meant to run together.
+    breaks: true,
+    async: false,
+  });
+}
+
 /** Escapes a value for an iCalendar TEXT property (RFC 5545 §3.3.11). */
 function escapeText(value: string): string {
   return value
@@ -147,13 +179,23 @@ function vevent(event: OteEvent, dtstamp: string): string[] {
   // Both event.url and location.onlineUrl map to iCal URL. The canonical page
   // wins; when both exist the attend link is preserved in DESCRIPTION.
   const url = event.url ?? event.location?.onlineUrl;
+  // Built in lockstep with descriptionParts: Outlook ignores DESCRIPTION
+  // entirely once X-ALT-DESC is present, so the HTML version must carry
+  // every fact the plain-text one does, not just the rendered description.
   const descriptionParts: string[] = [];
-  if (event.description) descriptionParts.push(event.description);
+  const htmlParts: string[] = [];
+  if (event.description) {
+    descriptionParts.push(event.description);
+    htmlParts.push(descriptionToHtml(event.description));
+  }
   if (event.url && event.location?.onlineUrl) {
     descriptionParts.push(`Online: ${event.location.onlineUrl}`);
+    const onlineUrl = escapeHtml(event.location.onlineUrl);
+    htmlParts.push(`<p>Online: <a href="${onlineUrl}">${onlineUrl}</a></p>`);
   }
   if (event.status === "moved-online") {
     descriptionParts.push("This event has moved online.");
+    htmlParts.push("<p>This event has moved online.</p>");
   }
   // offers/cfp/eligibility have no iCalendar structure to hold them (accepted
   // total loss, per the spec's own mapping tables) — degraded to readable
@@ -162,10 +204,17 @@ function vevent(event: OteEvent, dtstamp: string): string[] {
   if (event.cfp) {
     const window = event.cfp.closesAt ? ` (closes ${event.cfp.closesAt})` : "";
     descriptionParts.push(`Call for proposals: ${event.cfp.url}${window}`);
+    const cfpUrl = escapeHtml(event.cfp.url);
+    htmlParts.push(
+      `<p>Call for proposals: <a href="${cfpUrl}">${cfpUrl}</a>${escapeHtml(window)}</p>`,
+    );
   }
   if (event.eligibility) {
     const note = event.eligibility.note ? ` — ${event.eligibility.note}` : "";
     descriptionParts.push(`Eligibility: ${event.eligibility.type}${note}`);
+    htmlParts.push(
+      `<p>Eligibility: ${escapeHtml(event.eligibility.type)}${escapeHtml(note)}</p>`,
+    );
   }
   if (event.offers && event.offers.length > 0) {
     const offerLines = event.offers.map((o) => {
@@ -174,6 +223,7 @@ function vevent(event: OteEvent, dtstamp: string): string[] {
       return [o.name, price, o.url].filter((part): part is string => Boolean(part)).join(" — ");
     });
     descriptionParts.push(`Tickets:\n${offerLines.join("\n")}`);
+    htmlParts.push(`<p>Tickets:<br/>${offerLines.map(escapeHtml).join("<br/>")}</p>`);
   }
   if (descriptionParts.length > 0) {
     lines.push(
@@ -183,6 +233,14 @@ function vevent(event: OteEvent, dtstamp: string): string[] {
       ),
     );
   }
+  if (htmlParts.length > 0) {
+    lines.push(
+      ...prop(
+        withLanguage("X-ALT-DESC;FMTTYPE=text/html", event.textLanguage),
+        escapeText(htmlParts.join("\n")),
+      ),
+    );
+  }
 
   if (event.location?.venue) {
     lines.push(...prop("LOCATION", escapeText(event.location.venue)));

packages/export-ics/test/cli.test.ts

@@ -34,7 +34,7 @@ describe("ote-export-ics CLI", () => {
     const out = join(mkdtempSync(join(tmpdir(), "ote-export-ics-")), "feed.ics");
     expect(runCli([fixture, out], io)).toBe(0);
     expect(readFileSync(out, "utf8")).toContain("BEGIN:VCALENDAR");
-    expect(io.outLines[0]).toContain("6 events");
+    expect(io.outLines[0]).toContain("7 events");
   });
 
   it("invalid feed → exit 1 with validation errors", () => {

packages/export-ics/test/export-ics.test.ts

@@ -159,6 +159,33 @@ describe("feedToIcs", () => {
     expect(vevent).toContain("This event has moved online.");
   });
 
+  it("renders event.description as Markdown into X-ALT-DESC;FMTTYPE=text/html, alongside plain-text DESCRIPTION", () => {
+    const vevent = veventFor("https://mdtest.example/2026-11");
+    expect(vevent).toContain("X-ALT-DESC;FMTTYPE=text/html:");
+    expect(vevent).toContain("<strong>Bold</strong>");
+    expect(vevent).toContain('<a href="https://example.org/info">link</a>');
+    // DESCRIPTION stays the literal Markdown source — the universal
+    // plain-text fallback for clients that don't read X-ALT-DESC.
+    expect(vevent).toContain("DESCRIPTION:**Bold** intro");
+  });
+
+  it("escapes raw HTML found inside a Markdown description instead of passing it through live", () => {
+    const vevent = veventFor("https://mdtest.example/2026-11");
+    const altDesc = vevent
+      .split("\r\n")
+      .find((line) => line.startsWith("X-ALT-DESC;FMTTYPE=text/html:"));
+    expect(altDesc).not.toContain("<script>");
+    // escapeHtml runs first ("&lt;script&gt;"), then escapeText backslash-
+    // escapes the semicolons in those entities for the TEXT wire format.
+    expect(altDesc).toContain("&lt\\;script&gt\\;");
+  });
+
+  it("omits X-ALT-DESC when there is nothing to put in it", () => {
+    expect(veventFor("https://minimal.example/meetup/2026-09")).not.toContain(
+      "X-ALT-DESC",
+    );
+  });
+
   it("folds every content line at 75 octets", () => {
     const encoder = new TextEncoder();
     const lines = ics.split("\r\n");

packages/export-rss/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@opentechevents/export-rss` are documented here.
 
+## 0.3.1
+
+- `description` (plain text or Markdown, per the OTE spec) is now rendered to
+  HTML before being embedded in the item body, instead of being escaped as
+  literal text with newlines turned into `<br/>`. Raw inline/block HTML found
+  in the Markdown source is escaped rather than passed through live.
+- `parse.ts`'s reverse-parser (used by `apps/preview`) now reads every
+  top-level block in the item body, not just `<p>` elements, so Markdown
+  lists/headings/blockquotes in the description survive the round trip.
+
 ## 0.3.0
 
 - Initial package release for OTE spec v0.3.

packages/export-rss/README.md

@@ -56,6 +56,15 @@ Decisions worth knowing:
   (`parse.ts`, used by the preview app) — which only recognizes those five
   labels — reads them as part of the free-text description instead of
   silently dropping an unrecognized label.
+- **`description` is plain text or Markdown (OTE spec)** and is rendered to
+  HTML before being embedded (entity-encoded, per the point above) — so a
+  feed reader that treats `<description>` as markup shows real formatting
+  (bold, links, lists) instead of literal Markdown syntax. Raw inline/block
+  HTML found inside the Markdown source is escaped rather than passed
+  through live, so it can't smuggle real markup into whatever renders the
+  item body. A lone newline is treated as a line break (`breaks: true`),
+  since a short plain-text description is the common case and a single `\n`
+  in one reads as an intended break, not two words meant to run together.
 - **`feed.license` is optional (D029).** When every event declares its own
   license instead of a shared feed-level one, there's no single value for
   channel `copyright` to state — RSS's channel model has no per-item

packages/export-rss/fixtures/feed.json

@@ -102,6 +102,13 @@
       "timezone": "Europe/Madrid",
       "status": "moved-online",
       "location": { "onlineUrl": "https://meet.example/pydata-madrid" }
+    },
+    {
+      "id": "https://mdtest.example/2026-11",
+      "name": "Markdown description test",
+      "description": "**Bold** intro with a [link](https://example.org/info).\n\n<script>alert(1)</script> should not run.",
+      "startDate": "2026-11-03T18:00",
+      "timezone": "Europe/Madrid"
     }
   ]
 }