Fix documentation rendering issues

[osa1]

Replace < and > in documentation comments with &lt and &gt so
that they won't be interpreted as HTML tags and will render as expected.

In one place where we show Dart code with angle bracket I've replaced
the wrapping [ and ] with backticks.

Fixes CI.

[mkustermann]

... that they won't be interpreted as HTML tags and will render as expected.

I would assume that api docs would html-escape any text it's trying to render and not just blindly take the text and paste it in a <div> (or other) element. The comments are not HTML markup.

[osa1]

I think it's Markdown semantics that tags are copied directly. You can try it with an online Markdown renderer, e.g. try entering <foo>test</foo> in https://markdownlivepreview.com/ or https://stackedit.io/app#.

I'm not an expert, but there aren't a fixed set of tags that are valid in HTML, see e.g. https://stackoverflow.com/questions/2802687/is-there-a-way-to-create-your-own-html-tag-in-html5.

[mkustermann]

If it's supposed to work like that, lgtm (I can see a single place in package:flutter docs where they also do this)

I think it's Markdown semantics that tags are copied directly.

At least <script>...</script> tags don't seem to be copied (which would be pretty bad - imagine malicious users put <script ....> links into dart comments, publish package to pub and then other users go to api docs and suddenly 3rd party JavaScript runs when viewing API docs)

/cc @srawlins

[osa1]

AFAIU HTML sanitization is left to the user, see https://pub.dev/documentation/markdown/latest (search for "HTML sanitization").

This code just runs the script when you navigate to the documentation page:

/// Test <script>alert('hi');</script> test.
int calculate() {
  return 6 * 7;
}

In elsewhere where you get Markdown input from the user you would have to check the tags yourself.

[mkustermann]

This code just runs the script when you navigate to the documentation page:

/// Test <script>alert('hi');</script> test.
int calculate() {
  return 6 * 7;
}

/cc @jonasfj Do we allow 3rd party JavaScript to run on the API docs we host? Is this expected?

[jonasfj]

On pub.dev we run rendered markdown through:
https://pub.dev/packages/sanitize_html

In dartdoc there is a --sanitize-html option, which triggers:
https://github.com/dart-lang/dartdoc/blob/ce098154b16255bbc9ddfa89e3f6141262645513/lib/src/render/documentation_renderer.dart#L94

that's effectively an embedded fork of package:sanitize_html, which is then used to sanitize HTML tags.

---

In summary:

• <script>alert('hi');</script> will not be embedded in the HTML pages served on pub.dev.
  • Non-allowlisted tags are stripped through HTML sanitization.
• Should disallowed tags make it through HTML sanitization somehow, we have CSP headers in place which will:
  • Prevent execution of embedded <script> and <style> blocks, and,
  • Specify an allowlist of the domains from which external JS and CSS can be loaded.

---

On topic:

• Yes, markdown allows embedded HTML tags (including <script>).
• Documentation authors should avoid accidental creation of HTML tags, by:

  • Using < and > instead of < and > (respectively); or;

  • Use backticks around inline code snippets:

    /// Test `<script>alert('hi');</script>` test.

  • Use a code block

    ```html
    <script>alert('hi');</script>
    ```
    

Obviously, in this case, just use backticks around the inline code snippet.