@blockquote/to-markdown

Individual NPM package from the following PR

Custom-elements.json is a file format that describes custom elements. This format will allow tooling and IDEs to give rich information about the custom elements in a given project. It is, however, very experimental and things are subject to change. Follow the discussion here.

This library takes a Custom Elements Manifest and renders it to markdown.

Usage

Install:

npm i -S @blockquote/to-markdown

Import and use in your code:

import fs from 'fs';
import { customElementsManifestToMarkdown } from '@blockquote/to-markdown';

const manifest = JSON.parse(fs.readFileSync('./custom-elements.json', 'utf-8'));
const markdown = customElementsManifestToMarkdown(manifest);

fs.writeFileSync('./custom-elements.md', markdown);

Options

| Option | Type | Default | Description | | ------------- | ---------------------------- | ------- | ----------- | | headingOffset | Integer | 0 | Offset the heading level by this number | | mainDescription | Boolean | true | Show description field for Class and Mixins | | private | 'all'\|'details'\|'hidden' | 'all' | See Private Members | | omitDeclarations | OptionalDeclarations[] | [] | See Omit Declarations | | omitSections | OptionalSections[] | [] | See Omit Sections | | classNameFilter | string \| (() => string) | '.*' | See Class Name Filter |

Private Members

The private option controls how private members appear in the markdown.

• 'all': private members appear alongside public members according to source order
• 'hidden': private members do not appear at all in markdown, but protected members do
• 'details': private and protected members appear in a details disclosure widget below the table

Omit Declarations

The omitDeclarations option is a string[] that controls which kinds of entities are rendered in the final markdown output. The four declaration types are:

• mixins
• variables
• functions
• exports

The following is an example config that would filter out all four declaration types:

customElementsManifestToMarkdown(manifest, {
  omitDeclarations: ['mixins', 'variables', 'functions', 'exports' ]
})

**Note: ** Mixins can be rendered both as declarations AND as sections inside a declaration. The omitDeclarations option for mixins will only filter out top level mixin declarations. To filter out mixin sections from a class declaration, use the mixin filter from omitSections.

Omit Sections

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"
• mainDescription : "main-description"
• superClass : "super-class"
• fields : "fields"
• methods : "methods"
• staticFields : "static-fields"
• staticMethods : "static-methods"
• slots : "slots"
• events : "events"
• attributes : "attributes"
• cssProperties : "css-properties"
• cssParts : "css-parts"
• mixins : "main-heading"

The following is an example config showing how to filter out a few sections:

customElementsManifestToMarkdown(manifest, {
  // static fields and static methods tables will not be present
  // in the markdown result
  omitSections: [ 'super-class', 'static-methods', 'fields' ]
})

Class Name Filter

Depending on the source files you pass to the analyzer, your custom-elements-manifest.json may contain more class file declarations than you need for the final markdown output. The classNameFilter option accepts a regex as a string (or a function that returns one) that will be used to filter out class declarations before rendering.

customElementsManifestToMarkdown(manifest, {
  classNameFilter: () => {
    // some logic
    return `(${prefix}-*|SuperClassExact)`; // filters out every class name that doesnt match the regex provided
  }
})

Demo

customElementsManifestToMarkdown(manifest, {
  headingOffset: 1,
  private: 'details',
})

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "./fixtures/-TEST/package/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "description": "My description",
          "name": "SuperClass",
          "events": [
            {
              "name": "custom-event",
              "type": {
                "text": "SuperCustomEvent"
              },
              "description": "this is custom"
            }
          ],
          "superclass": {
            "name": "LitElement",
            "package": "lit-element"
          },
          "members": [
            {
              "kind": "method",
              "name": "superClassMethod",
              "privacy": "public"
            }
          ]
        },
        {
          "kind": "class",
          "name": "MyElement",
          "cssProperties": [
            {
              "name": "--background-color",
              "description": "Controls the color of bar"
            }
          ],
          "cssParts": [
            {
              "name": "bar",
              "description": "Styles the color of bar"
            }
          ],
          "slots": [
            {
              "name": "container",
              "description": "You can put some elements here"
            }
          ],
          "events": [
            {
              "name": "my-event",
              "type": {
                "text": "Event"
              }
            },
            {
              "name": "custom-event",
              "type": {
                "text": "SuperCustomEvent"
              },
              "description": "this is custom",
              "inheritedFrom": {
                "name": "SuperClass",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            }
          ],
          "mixins": [
            {
              "name": "LocalizeMixin",
              "package": "lion"
            },
            {
              "name": "Mixin",
              "module": "./fixtures/-TEST/package/my-element.js"
            }
          ],
          "superclass": {
            "name": "SuperClass",
            "module": "./fixtures/-TEST/package/my-element.js"
          },
          "attributes": [
            {
              "name": "prop-1",
              "fieldName": "prop1"
            },
            {
              "name": "prop2",
              "fieldName": "prop2"
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "prop1",
              "privacy": "public"
            },
            {
              "kind": "field",
              "name": "prop2",
              "privacy": "public"
            },
            {
              "kind": "field",
              "name": "prop3",
              "privacy": "public",
              "type": {
                "text": "boolean"
              },
              "default": "true"
            },
            {
              "kind": "field",
              "name": "foo",
              "type": {
                "text": "string"
              },
              "privacy": "private",
              "description": "description goes here",
              "default": "'bar'"
            },
            {
              "kind": "method",
              "name": "instanceMethod",
              "privacy": "public",
              "description": "Some description of the method here",
              "return": {
                "type": {
                  "text": ""
                }
              },
              "parameters": [
                {
                  "name": "e",
                  "type": {
                    "text": "Event"
                  }
                },
                {
                  "name": "a",
                  "type": {
                    "text": "string"
                  },
                  "description": "some description"
                }
              ]
            },
            {
              "kind": "field",
              "name": "mixinProp",
              "type": {
                "text": "number"
              },
              "privacy": "protected",
              "default": "1",
              "inheritedFrom": {
                "name": "Mixin",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            },
            {
              "kind": "method",
              "name": "superClassMethod",
              "privacy": "public",
              "inheritedFrom": {
                "name": "SuperClass",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            }
          ],
          "tagName": "my-element"
        },
        {
          "kind": "variable",
          "name": "variableExport",
          "description": "this is a var export",
          "type": {
            "text": "boolean"
          }
        },
        {
          "kind": "variable",
          "name": "stringVariableExport",
          "description": "this is a string var export",
          "type": {
            "text": "string"
          }
        },
        {
          "kind": "function",
          "name": "functionExport",
          "description": "This is a function export",
          "return": {
            "type": {
              "text": "boolean"
            }
          },
          "parameters": [
            {
              "name": "a",
              "type": {
                "text": "string"
              }
            },
            {
              "name": "b",
              "type": {
                "text": "boolean"
              }
            }
          ]
        },
        {
          "kind": "mixin",
          "name": "MyMixin4",
          "parameters": [
            {
              "name": "klass",
              "type": {
                "text": "*"
              },
              "description": "This is the description"
            },
            {
              "name": "foo",
              "type": {
                "text": "string"
              },
              "description": "Description goes here"
            }
          ]
        },
        {
          "kind": "mixin",
          "name": "Mixin",
          "parameters": [
            {
              "name": "klass",
              "type": {
                "text": "*"
              },
              "description": "This is the description"
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "mixinProp",
              "type": {
                "text": "number"
              },
              "privacy": "protected",
              "default": "1"
            }
          ]
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "SuperClass",
          "declaration": {
            "name": "SuperClass",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "variableExport",
          "declaration": {
            "name": "variableExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "stringVariableExport",
          "declaration": {
            "name": "stringVariableExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "functionExport",
          "declaration": {
            "name": "functionExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        }
      ]
    }
  ]
}

My description

./fixtures/-TEST/package/my-element.js:

class: SuperClass

Superclass

| Name | Module | Package | | ---------- | ------ | ----------- | | LitElement | | lit-element |

Methods

| Name | Privacy | Description | Parameters | Return | Inherited From | | ---------------- | ------- | ----------- | ---------- | ------ | -------------- | | superClassMethod | public | | | | |

Events

| Name | Type | Description | Inherited From | | ------------ | ------------------ | -------------- | -------------- | | custom-event | SuperCustomEvent | this is custom | |

class: MyElement, my-element

Superclass

| Name | Module | Package | | ---------- | -------------------------------------- | ------- | | SuperClass | ./fixtures/-TEST/package/my-element.js | |

Mixins

| Name | Module | Package | | ------------- | -------------------------------------- | ------- | | LocalizeMixin | | lion | | Mixin | ./fixtures/-TEST/package/my-element.js | |

Fields

| Name | Privacy | Type | Default | Description | Inherited From | | ----- | ------- | --------- | ------- | ----------- | -------------- | | prop1 | public | | | | | | prop2 | public | | | | | | prop3 | public | boolean | true | | |

Methods

| Name | Privacy | Description | Parameters | Return | Inherited From | | ---------------- | ------- | ----------------------------------- | --------------------- | ------ | -------------- | | instanceMethod | public | Some description of the method here | e: Event, a: string | | | | superClassMethod | public | | | | SuperClass |

Events

| Name | Type | Description | Inherited From | | ------------ | ------------------ | -------------- | -------------- | | my-event | Event | | | | custom-event | SuperCustomEvent | this is custom | SuperClass |

Attributes

| Name | Field | Inherited From | | ------ | ----- | -------------- | | prop-1 | prop1 | | | prop2 | prop2 | |

CSS Properties

| Name | Description | | ------------------ | ------------------------- | | --background-color | Controls the color of bar |

Slots

| Name | Description | | --------- | ------------------------------ | | container | You can put some elements here |

Fields

| Name | Privacy | Type | Default | Description | Inherited From | | --------- | --------- | -------- | ------- | --------------------- | -------------- | | foo | private | string | 'bar' | description goes here | | | mixinProp | protected | number | 1 | | Mixin |

mixin: MyMixin4

Parameters

| Name | Type | Default | Description | | ----- | -------- | ------- | ----------------------- | | klass | * | | This is the description | | foo | string | | Description goes here |

mixin: Mixin

Parameters

| Name | Type | Default | Description | | ----- | ---- | ------- | ----------------------- | | klass | * | | This is the description |

Fields

| Name | Privacy | Type | Default | Description | Inherited From | | --------- | --------- | -------- | ------- | ----------- | -------------- | | mixinProp | protected | number | 1 | | |

Variables

| Name | Description | Type | | -------------------- | --------------------------- | --------- | | variableExport | this is a var export | boolean | | stringVariableExport | this is a string var export | string |

Functions

| Name | Description | Parameters | Return | | -------------- | ------------------------- | ----------------------- | --------- | | functionExport | This is a function export | a: string, b: boolean | boolean |

Exports

| Kind | Name | Declaration | Module | Package | | ------------------------- | -------------------- | -------------------- | -------------------------------------- | ------- | | js | SuperClass | SuperClass | ./fixtures/-TEST/package/my-element.js | | | custom-element-definition | my-element | MyElement | ./fixtures/-TEST/package/my-element.js | | | js | variableExport | variableExport | ./fixtures/-TEST/package/my-element.js | | | js | stringVariableExport | stringVariableExport | ./fixtures/-TEST/package/my-element.js | | | js | functionExport | functionExport | ./fixtures/-TEST/package/my-element.js | |