@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, {
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: () => {
return `(${prefix}-*|SuperClassExact)`;
}
})
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 |
|