feat(to-markdown): markdown descriptions

packages/to-markdown/README.md

@@ -62,6 +62,7 @@ customElementsManifestToMarkdown(manifest, {
 The `omitSections` option is a `string[]` that controls which sections of a declaration's full entry in the manifest.json should be rendered in the final markdown output. The section names are:
 
 - mainHeading : "main-heading"
+- description : "description"
 - superClass : "super-class"
 - fields : "fields"
 - methods : "methods"
@@ -118,6 +119,7 @@ customElementsManifestToMarkdown(manifest, {
         {
           "kind": "class",
           "name": "SuperClass",
+          "description" : "Description of the *class*.",
           "events": [
             {
               "name": "custom-event",
@@ -424,6 +426,8 @@ customElementsManifestToMarkdown(manifest, {
 
   ### class: `SuperClass`
 
+  Description of the *class*.
+
   #### Superclass
 
   | Name       | Module | Package     |

packages/to-markdown/fixtures/kitchen-sink/EXPECTED.md

@@ -2,6 +2,10 @@
 
 ## class: `SuperClass`
 
+This is a *super* class
+
+See [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/)
+
 ### Superclass
 
 | Name         | Module | Package     |

packages/to-markdown/fixtures/kitchen-sink/README.md

@@ -2,6 +2,10 @@
 
 ## class: `SuperClass`
 
+This is a *super* class
+
+See [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/)
+
 ### Superclass
 
 | Name         | Module | Package     |

packages/to-markdown/fixtures/kitchen-sink/custom-elements.json

@@ -9,6 +9,7 @@
         {
           "kind": "class",
           "name": "SuperClass",
+          "description": "This is a *super* class\n\nSee [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/)",
           "events": [
             {
               "name": "custom-event",

packages/to-markdown/index.js

@@ -10,7 +10,7 @@ import {
   isDefined
 } from './lib/fp.js';
 import * as CELLS from './lib/cells.js';
-import { serialize } from './lib/serialize.js';
+import { serialize, parse } from './lib/serialize.js';
 
 const line = html('<hr/>');
 
@@ -23,6 +23,7 @@ const DECLARATIONS = {
 
 const SECTIONS = {
   mainHeading: 'main-heading',
+  description: 'description',
   superClass: 'super-class',
   fields: 'fields', 
   methods: 'methods',
@@ -51,6 +52,26 @@ const declarationHeading = options =>
       ]
     );
 
+/** Options -> Declaration -> [Content] */
+const declarationDescription = options =>
+({ description }) => {
+  const headingOffset = 1 + (options?.headingOffset ?? 0);
+
+  try {
+    const contentNodes = parse(description).children || [];
+
+    contentNodes.forEach((node) => {
+      if (node.type === 'heading' && typeof node.depth === "number") {
+        node.depth = Math.min(node.depth + headingOffset, 6);
+      }
+    })
+
+    return contentNodes;
+  } catch {
+    return [];
+  }
+}
+
 /** String -> Descriptor */
 const defaultDescriptor = name =>
   ({ heading: capital(name), get: x => x?.[name] });
@@ -177,6 +198,7 @@ function makeModuleDoc(mod, options) {
 
   const makeTable = tableWithTitle(options);
   const makeHeading = declarationHeading(options);
+  const makeDescription = declarationDescription(options);
   const variablesDecl = filteredDeclarations(declarations, omittedDeclarations, classNameFilter).filter(kindIs('variable'));
   const functionsDecl = filteredDeclarations(declarations, omittedDeclarations, classNameFilter).filter(kindIs('function'));
 
@@ -193,6 +215,7 @@ function makeModuleDoc(mod, options) {
 
       const nodes = [
         !['mixin', 'class'].includes(kind) ? null : makeHeading(decl),
+        ...['mixin', 'class'].includes(kind) && optionEnabled(omittedSections.description) ? makeDescription(decl) : [],
         ...optionEnabled(omittedSections.superClass) ? makeTable('Superclass', [CELLS.NAME, 'module', 'package'], [decl.superclass]) : [],
         ...optionEnabled(omittedSections.mixins) ? makeTable('Mixins', [CELLS.NAME, 'module', 'package'], decl.mixins) : [],
         ...kind === 'mixin' && optionEnabled(omittedSections.mixins) ?  makeTable('Parameters', [CELLS.NAME, CELLS.TYPE, CELLS.DEFAULT, 'description'], decl.parameters) : [],

packages/to-markdown/types/main.d.ts

@@ -10,6 +10,7 @@ enum Declarations {
 
 enum Sections {
   mainHeading = 'main-heading',
+  description = 'description',
   superClass = 'super-class',
   fields = 'fields', 
   methods = 'methods',