Allow markdown readme above the gallery pages (#11103)

build-scripts/gulp/gallery.js

@@ -2,6 +2,7 @@
 const gulp = require("gulp");
 const fs = require("fs");
 const path = require("path");
+const marked = require("marked");
 
 const env = require("../env");
 const paths = require("../paths");
@@ -20,19 +21,46 @@ gulp.task("gather-gallery-demos", async function gatherDemos() {
     path.resolve(paths.gallery_dir, "src/demos")
   );
 
+  const galleryBuild = path.resolve(paths.gallery_dir, "build");
+  fs.mkdirSync(galleryBuild, { recursive: true });
+
   let content = "export const DEMOS = {\n";
 
   for (const file of files) {
+    if (!file.endsWith(".ts")) {
+      continue;
+    }
     const demoId = path.basename(file, ".ts");
-    const demoPath = "../src/demos/" + demoId;
+    const descriptionFile = path.resolve(
-    content += `  "${demoId.substring(5)}": () => import("${demoPath}"),\n`;
+      paths.gallery_dir,
+      "src/demos",
+      `${demoId}.markdown`
+    );
+    const hasDescription = fs.existsSync(descriptionFile);
+    if (hasDescription) {
+      const descriptionContent = fs.readFileSync(descriptionFile, "utf-8");
+      fs.writeFileSync(
+        path.resolve(galleryBuild, `${demoId}-description.ts`),
+        `
+        import {html} from "lit";
+        export default html\`${marked(descriptionContent)}\`
+        `
+      );
+    }
+    const demoPath = `../src/demos/${demoId}`;
+    const descriptionPath = `./${demoId}-description`;
+    content += `  "${demoId.substring(5)}": {
+      ${
+        hasDescription
+          ? `description: () => import("${descriptionPath}").then(m => m.default),`
+          : ""
+      }
+      load: () => import("${demoPath}")
+    },\n`;
   }
 
   content += "};";
 
-  const galleryBuild = path.resolve(paths.gallery_dir, "build");
-
-  fs.mkdirSync(galleryBuild, { recursive: true });
   fs.writeFileSync(
     path.resolve(galleryBuild, "import-demos.ts"),
     content,

gallery/src/demos/demo-ha-alert.markdown

@@ -0,0 +1,14 @@
+The `<ha-alert>` element is used to display a message to the user that requires attention.
+
+The `header` option should not be used without a description.
+
+
+Usage:
+
+```html
+<ha-alert type="info">Look, an alert!</ha-alert>
+```
+
+This will show:
+
+<ha-alert type="info">Look, an alert!</ha-alert>

gallery/src/ha-gallery.ts

@@ -3,6 +3,7 @@ import "@material/mwc-drawer";
 import "@material/mwc-top-app-bar-fixed";
 import { html, css, LitElement, PropertyValues } from "lit";
 import { customElement, property, query } from "lit/decorators";
+import { until } from "lit/directives/until";
 import "../../src/components/ha-icon-button";
 import "../../src/managers/notification-manager";
 import { haStyle } from "../../src/resources/styles";
@@ -99,7 +100,23 @@ class HaGallery extends LitElement {
 
             <div slot="title">${this._demo}</div>
           </mwc-top-app-bar-fixed>
-          <div>${dynamicElement(`demo-${this._demo}`)}</div>
+          <div>
+            ${DEMOS[this._demo].description
+              ? html`
+                  ${until(
+                    DEMOS[this._demo].description().then(
+                      (content) => html`
+                        <ha-card .header=${this._demo}>
+                          <div class="card-content">${content}</div>
+                        </ha-card>
+                      `
+                    ),
+                    ""
+                  )}
+                `
+              : ""}
+            ${dynamicElement(`demo-${this._demo}`)}
+          </div>
         </div>
       </mwc-drawer>
       <notification-manager
@@ -145,7 +162,7 @@ class HaGallery extends LitElement {
   updated(changedProps: PropertyValues) {
     super.updated(changedProps);
     if (changedProps.has("_demo") && this._demo) {
-      DEMOS[this._demo]();
+      DEMOS[this._demo].load();
     }
   }
 
@@ -196,6 +213,11 @@ class HaGallery extends LitElement {
         background-color: var(--sidebar-selected-icon-color);
         opacity: 0.12;
       }
+
+      ha-card {
+        max-width: 600px;
+        margin: 16px auto;
+      }
     `,
   ];
 }