From a1ab91bc091caf439ebea1f4977123fd851d4335 Mon Sep 17 00:00:00 2001
From: Benny Powers <web@bennypowers.com>
Date: Thu, 8 Jun 2023 11:59:16 +0300
Subject: [PATCH] fix(tools): use markdown headings on docspages

Allows downstream to use markdown-it plugins to manipulate output
e.g. by adding hash links to headers
---
 tools/pfe-tools/11ty/DocsPage.ts                         | 2 ++
 tools/pfe-tools/11ty/templates/attributes.njk            | 6 ++----
 tools/pfe-tools/11ty/templates/band.njk                  | 2 +-
 tools/pfe-tools/11ty/templates/css-custom-properties.njk | 6 ++----
 tools/pfe-tools/11ty/templates/css-shadow-parts.njk      | 6 ++----
 tools/pfe-tools/11ty/templates/events.njk                | 6 ++----
 tools/pfe-tools/11ty/templates/methods.njk               | 6 ++----
 tools/pfe-tools/11ty/templates/overview.njk              | 6 ++++--
 tools/pfe-tools/11ty/templates/properties.njk            | 6 ++----
 tools/pfe-tools/11ty/templates/slots.njk                 | 6 ++----
 10 files changed, 21 insertions(+), 31 deletions(-)

diff --git a/tools/pfe-tools/11ty/DocsPage.ts b/tools/pfe-tools/11ty/DocsPage.ts
index 5e3138c622..de60b0d4e6 100644
--- a/tools/pfe-tools/11ty/DocsPage.ts
+++ b/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;
   }
diff --git a/tools/pfe-tools/11ty/templates/attributes.njk b/tools/pfe-tools/11ty/templates/attributes.njk
index 57f7f98c5b..70814cb60d 100644
--- a/tools/pfe-tools/11ty/templates/attributes.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/band.njk b/tools/pfe-tools/11ty/templates/band.njk
index 6741214533..1335f6f217 100644
--- a/tools/pfe-tools/11ty/templates/band.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/css-custom-properties.njk b/tools/pfe-tools/11ty/templates/css-custom-properties.njk
index cc30d4b4b3..867af9e648 100644
--- a/tools/pfe-tools/11ty/templates/css-custom-properties.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/css-shadow-parts.njk b/tools/pfe-tools/11ty/templates/css-shadow-parts.njk
index 141d7c1194..ad85790c87 100644
--- a/tools/pfe-tools/11ty/templates/css-shadow-parts.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/events.njk b/tools/pfe-tools/11ty/templates/events.njk
index 670400d0d5..445c90ab54 100644
--- a/tools/pfe-tools/11ty/templates/events.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/methods.njk b/tools/pfe-tools/11ty/templates/methods.njk
index fd082a4f85..95abe5eec9 100644
--- a/tools/pfe-tools/11ty/templates/methods.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/overview.njk b/tools/pfe-tools/11ty/templates/overview.njk
index 8dc8ab4563..0db92138c6 100644
--- a/tools/pfe-tools/11ty/templates/overview.njk
+++ b/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 }}
diff --git a/tools/pfe-tools/11ty/templates/properties.njk b/tools/pfe-tools/11ty/templates/properties.njk
index 4145ed9e75..d61f3681ef 100644
--- a/tools/pfe-tools/11ty/templates/properties.njk
+++ b/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>
diff --git a/tools/pfe-tools/11ty/templates/slots.njk b/tools/pfe-tools/11ty/templates/slots.njk
index 6031323ea6..f7d210254b 100644
--- a/tools/pfe-tools/11ty/templates/slots.njk
+++ b/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 -%}