Included Github issues sometimes contain invalid HTML

[pchampin]

Including github issues in a respec document is a great features, but Github is sometimes producing invalid HTML (see for example https://github.com/w3c/rdf-star/issues/121). Some of these errors occur in the text that Respec copies inside the issue block. It follows that the document generated by Respec is rejected by the HTML validator.

I understand that this problem is maybe not for Respec to fix. But I think it is good to at least document it here.

[sidvishnoi]

I understand that this problem is maybe not for Respec to fix. But I think it is good to at least document it here.

Yes. It's somewhat difficult to fix and get a result similar to GitHub, but one that validator accepts. Currently, we make use of bodyHTML (see below) and inject it as is, which works for most cases. GitHub API can also return:

• bodyText: plain text but with newlines, loses most of the formatting details,
• body: something we can render on ReSpec client-side using marked (if it's certain that GitHub strips potential XSS vulnerabilities).

GitHub API query for above issue

# run it at https://docs.github.com/en/graphql/overview/explorer
{
  repository(owner: "w3c", name: "rdf-star") {
    issue(number: 121) {
      title
      body
      bodyText
      bodyHTML
    }
  }
}

API response for above query

{
  "data": {
    "repository": {
      "issue": {
        "title": "Define comparison operations for RDF-star triples",
        "body": "As pointed out by @lisp and @jeenbroekstra [on the mailling list][1], we need to define how RDF-star triples are compared with each other and with other terms\r\n\r\n* [x] by `ORDER BY` ([Section 15.1 of the SPARQL 1.1 spec][2])\r\n* [x] by the `=` operator ([Section 17.4.1.7][3])\r\n* [x] by the `sameTerm` function ([Section 17.4.1.8][4])\r\n\r\n[1]: https://www.w3.org/mid/CAD8Bno9FjjO_m8Kc-T=iJq4TBeFFNULxPKq8E9=aVOUsE9GZCQ@mail.gmail.com\r\n[2]: https://www.w3.org/TR/sparql11-query/#modOrderBy\r\n[3]: https://www.w3.org/TR/sparql11-query/#func-RDFterm-equal\r\n[4]: https://www.w3.org/TR/sparql11-query/#func-sameTerm\r\n",
        "bodyText": "As pointed out by @lisp and @jeenbroekstra on the mailling list, we need to define how RDF-star triples are compared with each other and with other terms\n\n by ORDER BY (Section 15.1 of the SPARQL 1.1 spec)\n by the = operator (Section 17.4.1.7)\n by the sameTerm function (Section 17.4.1.8)",
        "bodyHTML": "<p>As pointed out by <a class=\"user-mention\" data-hovercard-type=\"user\" data-hovercard-url=\"/users/lisp/hovercard\" data-octo-click=\"hovercard-link-click\" data-octo-dimensions=\"link_type:self\" href=\"https://github.com/lisp\">@lisp</a> and <a class=\"user-mention\" data-hovercard-type=\"user\" data-hovercard-url=\"/users/jeenbroekstra/hovercard\" data-octo-click=\"hovercard-link-click\" data-octo-dimensions=\"link_type:self\" href=\"https://github.com/jeenbroekstra\">@jeenbroekstra</a> <a href=\"https://www.w3.org/mid/CAD8Bno9FjjO_m8Kc-T=iJq4TBeFFNULxPKq8E9=aVOUsE9GZCQ@mail.gmail.com\" rel=\"nofollow\">on the mailling list</a>, we need to define how RDF-star triples are compared with each other and with other terms</p>\n<ul class=\"contains-task-list\">\n<li class=\"task-list-item\"><input type=\"checkbox\" id=\"\" disabled=\"\" class=\"task-list-item-checkbox\" checked=\"\"> by <code>ORDER BY</code> (<a href=\"https://www.w3.org/TR/sparql11-query/#modOrderBy\" rel=\"nofollow\">Section 15.1 of the SPARQL 1.1 spec</a>)</li>\n<li class=\"task-list-item\"><input type=\"checkbox\" id=\"\" disabled=\"\" class=\"task-list-item-checkbox\" checked=\"\"> by the <code>=</code> operator (<a href=\"https://www.w3.org/TR/sparql11-query/#func-RDFterm-equal\" rel=\"nofollow\">Section 17.4.1.7</a>)</li>\n<li class=\"task-list-item\"><input type=\"checkbox\" id=\"\" disabled=\"\" class=\"task-list-item-checkbox\" checked=\"\"> by the <code>sameTerm</code> function (<a href=\"https://www.w3.org/TR/sparql11-query/#func-sameTerm\" rel=\"nofollow\">Section 17.4.1.8</a>)</li>\n</ul>"
      }
    }
  }
}

For now, we can document this better, and suggest adding body manually so ReSpec doesn't override it with invalid markup.