issue-markdown

Issue and comment Markdown

Use this skill when generating or changing Markdown published to issues, comments, or reviews, especially in actions/setup/js/. Build a Report tree first; render only the complete document. Do not assemble Markdown using interpolation, concatenation, body +=, or arrays of Markdown strings joined with newlines. Parsing an assembled string afterward is not a tree-first refactor.

Find publication paths

Search production .cjs files for issues.create, issues.update, createComment, updateComment, createReview, createReplyForReviewComment, and GraphQL body variables. Trace each body back through shared helpers, fallback comments, retries, staged previews, and append/prepend/replace-island updates. Exclude test fixtures, HTTP payload assembly, and step-summary-only output. Jira ADF text is not Markdown: preserve its literal entities, Unicode, and paragraphs instead of routing it through the Markdown parser or renderer.

Use the existing tree

actions/setup/js/report_ast.cjs defines Report, ReportBlock, and ReportInline. Use JSDoc annotations so npm run typecheck verifies node kinds:

/** @type {import("./report_ast.cjs").Report} */
const report = {
  type: "report",
  title: "Workflow result",
  children: [
    {
      type: "paragraph",
      agentTainted: false,
      children: [
        { type: "text", value: "Created related issue: ", agentTainted: false },
        { type: "issue_reference", number: String(issue.number), agentTainted: false },
      ],
    },
    { type: "code_block", language: "text", value: diagnostic, agentTainted: true },
  ],
};

Use heading, paragraph, list, table, details, quote, alert, separator, code_block, and typed inline nodes instead of Markdown punctuation. GitHub [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] map to alert nodes with the matching kind; the renderer emits their markers. Keep alerts separate rather than nesting them inside another alert, which GitHub does not support. Preserve supported <sub> formatting in details summaries. Use xml_marker, json_marker, expiration, and closing_reference for machine metadata and closing links. Preserve xml_marker.compact for identifiers whose exact spelling is used by cleanup. Use review_marker for the durable, URI-encoded review caller reference; keep the authoritative marker last. Dynamic labels, paths, errors, and identifiers belong in text/code nodes; link destinations belong in link.url.