Add support and styling for custom <callout-box> HTML tags

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 9.0.7-wip
+* Add built-in CSS styling for the <example> HTML tag to support highlighted code examples.
+
 ## 9.0.6
 * Require analyzer 13.0.2 APIs.
 * Introduce the {@example} directive for embedding external files, with support for extracting specific code blocks via #region tags.

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v9.0.6/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v9.0.7-wip/%f%#L%l%'

lib/src/render/documentation_renderer.dart

@@ -206,6 +206,7 @@ final _allowedElements = <String>{
   'SPAN',
   'TIME',
   'WBR',
+  'EXAMPLE',
 };
 
 // Inspired by the set of HTML attributes allowed in GFM.

lib/src/version.dart

@@ -1 +1 @@
-const packageVersion = '9.0.6';
+const packageVersion = '9.0.7';

pubspec.yaml

@@ -1,5 +1,5 @@
 name: dartdoc
-version: 9.0.6
+version: 9.0.7-wip
 description: A non-interactive HTML documentation generator for Dart source code.
 repository: https://github.com/dart-lang/dartdoc
 

test/end2end/model_special_cases_test.dart

@@ -182,6 +182,7 @@ void main() {
     Class classWithHtml;
     late final Method blockHtml;
     late final Method inlineHtml;
+    late final Method customExampleHtml;
     late final PackageGraph packageGraph;
     late final Library exLibrary;
 
@@ -198,6 +199,7 @@ void main() {
       classWithHtml = exLibrary.classes.named('SanitizableHtml');
       blockHtml = classWithHtml.instanceMethods.named('blockHtml');
       inlineHtml = classWithHtml.instanceMethods.named('inlineHtml');
+      customExampleHtml = classWithHtml.instanceMethods.named('customExampleHtml');
       for (var modelElement in packageGraph.localPublicLibraries
           .expand((l) => l.allModelElements)) {
         // Accessing this getter triggers documentation-processing.
@@ -240,6 +242,10 @@ void main() {
     test('removes bad block HTML', () {
       expect(blockHtml.documentationAsHtml, isNot(contains('bad-idea')));
     });
+
+    test('can have example HTML', () {
+      expect(customExampleHtml.documentationAsHtml, contains('<example>'));
+    });
   });
 
   group('HTML Injection when allowed', () {

testing/test_package_sanitize_html/lib/test_package_sanitize_html.dart

@@ -29,4 +29,9 @@ abstract class SanitizableHtml {
   ///
   /// This is a <a href="javascript:alert('bad-idea');">bad</a> link.
   void inlineHtml();
+
+  /// Tests custom example tags
+  ///
+  /// <example>A fine example</example>
+  void customExampleHtml();
 }

web/sig.txt

@@ -1 +1 @@
-67C19593977E0B284E58447F539D330E
+7848C06D1465C90600DD56527148A5AB

web/styles/_content.scss

@@ -142,3 +142,23 @@ th,
 td {
   padding: 8px;
 }
+
+example {
+  padding: 10px;
+  overflow: auto;
+  display: block;
+  unicode-bidi: isolate;
+  margin: 1em 0;
+}
+
+example p {
+  margin: 8px 40px 12px 8px;
+}
+
+example pre {
+  margin: 0;
+}
+
+example code.hljs {
+  max-height: 500px;
+}

web/styles/_theme.scss

@@ -58,6 +58,10 @@
   img[src$="#gh-dark-mode-only"] {
     display: none;
   }
+
+  example {
+    background-color: rgb(215, 235, 252);
+  }
 }
 
 .dark-theme {
@@ -109,6 +113,10 @@
   img[src$="#gh-light-mode-only"] {
     display: none;
   }
+
+  example {
+    background-color: rgb(30, 40, 51);
+  }
 }
 
 #theme-button {