Allow ID attributes on headings when running with --sanitize-html (#3358)

* Allow ID attributes on headings when running with --sanitize-html

* Organize imports

* Additional tests

Author: jonasfj

lib/src/render/documentation_renderer.dart

@@ -307,6 +307,20 @@ final _citeAttributeValidator = <String, bool Function(String)>{
   'cite': _validUrl,
 };
 
+/// Allow the `id` attribute for `h1`, `h2`, ... `h6`.
+final _headingAttributeValidator = <String, bool Function(String)>{
+  'id': (id) {
+    // This id property is generated by package:markdown in:
+    // https://github.com/dart-lang/markdown/blob/ecbffa9bf9109d490b9388e9cb1f2bb801aee63c/lib/src/block_syntaxes/block_syntax.dart#L57-L63
+
+    // Cannot contain anything but a-z0-9_-
+    if (id.contains(RegExp('[^a-z0-9_-]'))) {
+      return false;
+    }
+    return true;
+  },
+};
+
 final _elementAttributeValidators =
     <String, Map<String, bool Function(String)>>{
   'A': {
@@ -324,4 +338,12 @@ final _elementAttributeValidators =
   'DEL': _citeAttributeValidator,
   'INS': _citeAttributeValidator,
   'Q': _citeAttributeValidator,
+  'H1': _headingAttributeValidator,
+  'H2': _headingAttributeValidator,
+  'H3': _headingAttributeValidator,
+  'H4': _headingAttributeValidator,
+  'H5': _headingAttributeValidator,
+  'H6': _headingAttributeValidator,
+  'H7': _headingAttributeValidator,
+  'H8': _headingAttributeValidator,
 };

test/end2end/model_special_cases_test.dart

@@ -15,6 +15,7 @@ import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_config_provider.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:dartdoc/src/special_elements.dart';
+import 'package:html/parser.dart' as html;
 import 'package:test/test.dart';
 
 import '../src/utils.dart' as utils;
@@ -211,9 +212,8 @@ void main() {
     Class classWithHtml;
     late final Method blockHtml;
     late final Method inlineHtml;
-
-    PackageGraph packageGraph;
-    Library exLibrary;
+    late final PackageGraph packageGraph;
+    late final Library exLibrary;
 
     setUpAll(() async {
       packageGraph = await utils.bootBasicPackage(
@@ -237,6 +237,21 @@ void main() {
       }
     });
 
+    test('can have auto-generated id attributes on headings', () {
+      final dom = html.parseFragment(exLibrary.documentationAsHtml);
+      expect(dom.querySelector('h1[id="heading-with-id"]'), isNotNull);
+    });
+
+    test('can have id attributes on headings', () {
+      final dom = html.parseFragment(exLibrary.documentationAsHtml);
+      expect(dom.querySelector('h1[id="my-id"]'), isNotNull);
+    });
+
+    test('cannot have capital id attributes on headings', () {
+      final dom = html.parseFragment(exLibrary.documentationAsHtml);
+      expect(dom.querySelector('h1[id="MY-ID"]'), isNull);
+    });
+
     test('can have inline HTML', () {
       expect(inlineHtml.documentationAsHtml, contains('<small>'));
     });

testing/test_package_sanitize_html/lib/test_package_sanitize_html.dart

@@ -1,3 +1,13 @@
+/// My library
+///
+/// See [heading](#heading-with-id).
+///
+/// <h1 id="my-id">headline with custom id</h1>
+///
+/// <h1 id="MY-ID">headline with disallowed id</h1>
+///
+/// # Heading with id
+///  * what a topic
 library ex;
 
 abstract class SanitizableHtml {