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

Source

{
  "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"
          }
        }
      ]
    }
  ]
}

Result

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