feat(tools): add renderTitleInOverview option to cem 11ty plugin (#2444)

Author: bennypowers

.changeset/cem-11ty-title.md

@@ -0,0 +1,30 @@
+---
+"@patternfly/pfe-tools": minor
+---
+
+`11ty/plugins/custom-elements-manifest.cjs`: added `renderTitleInOverview` 
+option, a boolean flag which defaults to `true`.
+
+When true, this option renders an `<h1>` in the element's docs page's "Overview" 
+section.
+
+Note: the next major release will switch this option to `false` by default, so 
+to prepare your docs pages, add your own headings:
+
+BEFORE:
+```md
+{% renderOverview %}
+  <pf-jazz-hands></pf-jazz-hands>
+{% endrenderOverview %}
+```
+
+AFTER:
+```md
+<section class="band">
+  <h1 id="jazz-hands">Jazz Hands</h1>
+</section>
+
+{% renderOverview %}
+  <pf-jazz-hands></pf-jazz-hands>
+{% endrenderOverview %}
+```

tools/create-element/templates/element/docs/element.md

@@ -14,4 +14,4 @@
 
 {% renderCssCustomProperties %}{% endrenderCssCustomProperties %}
 
-{% renderCssParts %}{% endrenderCssParts %}
+{% renderCssParts %}{% endrenderCssParts %}

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

@@ -13,6 +13,8 @@ interface DocsPageOptions extends PfeConfig {
   docsTemplatePath?: string;
   tagName?: string;
   title?: string;
+  /** When true, renders an <h1> with the element's title in the element docs overview */
+  renderTitleInOverview?: boolean;
 }
 
 export interface RenderKwargs {
@@ -69,7 +71,7 @@ export class DocsPage implements DocsPageRenderer {
 
   constructor(
     public manifest: Manifest,
-    options?: DocsPageOptions) {
+    private options?: DocsPageOptions) {
     this.tagName = options?.tagName ?? '';
     this.title = options?.title ?? Manifest.prettyTag(this.tagName);
     this.slug = slugify(options?.aliases?.[this.tagName] ?? this.tagName.replace(/^\w+-/, '')).toLowerCase();
@@ -103,7 +105,13 @@ export class DocsPage implements DocsPageRenderer {
   /** Render the overview of a component page */
   renderOverview(content: string, kwargs: RenderKwargs = {}) {
     const description = this.manifest.getDescription(this.#packageTagName(kwargs));
-    return this.templates.render('overview.njk', { description, content, ...kwargs });
+    const header = kwargs.title ?? this.title;
+    // TODO: switch to false in next major
+    const { renderTitleInOverview = true } = this.options ?? {};
+    const renderedTitle =
+        !renderTitleInOverview ? ''
+      : this.renderBand('', { level: 1, header });
+    return `${renderedTitle}\n${this.templates.render('overview.njk', { description, content, ...kwargs })}`;
   }
 
   /** Render the list of element attributes */

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

@@ -1,7 +1,3 @@
-<header class="band">
-  <h1>{{ title }}</h1>
-</header>
-
 <section class="band overview">
   <h2>Overview</h2>