@custom-elements-manifest/to-markdown

@custom-elements-manifest/to-markdown

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 @custom-elements-manifest/to-markdown

Import and use in your code:

import fs from 'fs';
import { customElementsManifestToMarkdown } from '@custom-elements-manifest/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
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, {
  omitSections: ['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
• superClass
• fields
• methods
• staticFields
• staticMethods
• slots
• events
• attributes
• cssProperties
• cssParts
• mixins

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: [ 'staticFields', 'staticMethods' ]
})

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',
})

Source

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "./fixtures/-TEST/package/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "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"
          }
        }
      ]
    }
  ]
}

Result

./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

Private API

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

Private API

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