fix(tools): use markdown headings on docspages (#2516)

Allows downstream to use markdown-it plugins to manipulate output
e.g. by adding hash links to headers

Co-authored-by: Steven Spriggs <[email protected]>

Author: bennypowers

tools/pfe-tools/11ty/DocsPage.ts

@@ -85,6 +85,8 @@ export class DocsPage implements DocsPageRenderer {
     this.templates.addFilter('log', DocsPage.#log);
     this.templates.addFilter('type', DocsPage.#type);
     this.templates.addFilter('innerMD', DocsPage.#innerMD);
+    this.templates.addFilter('mdHeading', (header, length = 2) =>
+      DocsPage.#innerMD(`${Array.from({ length }, () => '#').join('')} ${header}`));
     this.templates.addFilter('stringifyParams', DocsPage.#stringifyParams);
     this.docsTemplatePath = options?.docsTemplatePath;
   }

tools/pfe-tools/11ty/templates/attributes.njk

@@ -2,7 +2,7 @@
 {% set header = header or 'Attributes' %}
 
 <section class="band api attributes api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not attributes.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not attributes.length %}
 
   <em>None</em> {%- else -%}
 
@@ -20,9 +20,7 @@
   </dl> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated ' + header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {%- for attribute in deprecated -%}
       <dt><strong><code>{{ attribute.name }}</code></strong></dt>
       <dd>

tools/pfe-tools/11ty/templates/band.njk

@@ -1,6 +1,6 @@
 {% set level = level or 2 %}
 
 <section class="band">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}>
+  {{ header | mdHeading(level) | safe }}
   {{ content | innerMD | safe }}
 </section>

tools/pfe-tools/11ty/templates/css-custom-properties.njk

@@ -11,7 +11,7 @@
 
 <section class="api band css-custom-properties api-properties">
   <a id="styling-hooks"></a>
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not cssProperties.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not cssProperties.length %}
 
   <em>None</em> {%- else -%}
 
@@ -37,9 +37,7 @@
   </table> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated ' + header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <table>
       <thead>
         <tr>

tools/pfe-tools/11ty/templates/css-shadow-parts.njk

@@ -2,7 +2,7 @@
 {% set header = header or 'CSS Shadow Parts' %}
 
 <section class="api band css-shadow-parts api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not parts.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not parts.length %}
 
   <em>None</em> {%- else -%}
 
@@ -14,9 +14,7 @@
   </dl> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated '+header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {% for part in deprecated -%}
       <dt><strong><code>{{ part.name }}</code></strong></dt>
       <dd>

tools/pfe-tools/11ty/templates/events.njk

@@ -2,7 +2,7 @@
 {% set header = header or 'Events' %}
 
 <section class="api band events api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not events.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not events.length %}
 
   <em>None</em> {% else %}
 
@@ -18,9 +18,7 @@
   </dl> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated ' + header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {%- for event in deprecated -%}
       <dt><strong><code>{{ event.name }}</code></strong></dt>
       <dd>

tools/pfe-tools/11ty/templates/methods.njk

@@ -4,7 +4,7 @@
 {# TODO: inline code highlighting for type and default: render the markdown to html and extract the `<code>` from the `<pre>` #}
 
 <section class="api band methods api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not methods.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not events.length %}
 
   <em>None</em> {% else %}
 
@@ -15,9 +15,7 @@
   </dl> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated '+header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {%- for method in deprecated -%}
       <dt><strong><code>{{ method.name }}({{ method | stringifyParams }})</code></strong></dt>
       <dd>

tools/pfe-tools/11ty/templates/overview.njk

@@ -1,5 +1,6 @@
 <section class="band overview">
-  <h2>Overview</h2>
+
+  ## Overview
 
   <div class="example-preview">
     {{ content | safe }}
@@ -8,7 +9,8 @@
 </section>
 
 <section class="band">
-  <h2>Installation</h2>
+
+  ## Installation
 
 ```shell
 npm install {{ package.name }}

tools/pfe-tools/11ty/templates/properties.njk

@@ -4,7 +4,7 @@
 {# TODO: inline code highlighting for type and default: render the markdown to html and extract the `<code>` from the `<pre>` #}
 
 <section class="api band properties api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not properties.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not properties.length %}
 
   <em>None</em> {% else %}
 
@@ -22,9 +22,7 @@
   </dl> {% endif %} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated ' + header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {%- for property in deprecated -%}
       <dt><strong><code>{{ property.name }}</code></strong></dt>
       <dd>

tools/pfe-tools/11ty/templates/slots.njk

@@ -2,7 +2,7 @@
 {% set header = header or 'Slots' %}
 
 <section class="api band slots api-properties">
-  <h{{level}}>{{ header | innerMD | safe }}</h{{level}}> {% if not content and not slots.length %}
+  {{ header | mdHeading(level) | safe }} {% if not content and not slots.length %}
 
   <em>None</em> {%- else -%}
 
@@ -17,9 +17,7 @@
   </dl> {%- endif -%} {%- if deprecated.length -%}
 
   <details>
-    <summary>
-      <h{{level+1}}>{{ ('Deprecated ' + header) | innerMD | safe }}</h{{level+1}}>
-    </summary>
+    <summary>{{ ('Deprecated ' + header) | mdHeading(level + 1) | safe }}</summary>
     <dl> {% for slot in deprecated -%}
       <dt> {%- if slot.name -%}
         <strong><code>{{ slot.name }}</code></strong> {%- else -%}