@custom-elements-manifest/to-markdown
Advanced tools
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
Readme
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.
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);
| 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 |
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 tableThe omitDeclarations option is a string[] that controls which kinds of entities are rendered in the final markdown output. The four declaration types are:
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.
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:
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' ]
})
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
}
})
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",
"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"
}
}
]
}
]
}
./fixtures/-TEST/package/my-element.js:SuperClass| Name | Module | Package |
|---|---|---|
| LitElement | lit-element |
| Name | Privacy | Description | Parameters | Return | Inherited From |
|---|---|---|---|---|---|
| superClassMethod | public |
| Name | Type | Description | Inherited From |
|---|---|---|---|
| custom-event | SuperCustomEvent | this is custom |
MyElement, my-element| Name | Module | Package |
|---|---|---|
| SuperClass | ./fixtures/-TEST/package/my-element.js |
| Name | Module | Package |
|---|---|---|
| LocalizeMixin | lion | |
| Mixin | ./fixtures/-TEST/package/my-element.js |
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
| prop1 | public | ||||
| prop2 | public | ||||
| prop3 | public | boolean | true |
| Name | Privacy | Description | Parameters | Return | Inherited From |
|---|---|---|---|---|---|
| instanceMethod | public | Some description of the method here | e: Event, a: string | ||
| superClassMethod | public | SuperClass |
| Name | Type | Description | Inherited From |
|---|---|---|---|
| my-event | Event | ||
| custom-event | SuperCustomEvent | this is custom | SuperClass |
| Name | Field | Inherited From |
|---|---|---|
| prop-1 | prop1 | |
| prop2 | prop2 |
| Name | Description |
|---|---|
| --background-color | Controls the color of bar |
| Name | Description |
|---|---|
| container | You can put some elements here |
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
| foo | private | string | 'bar' | description goes here | |
| mixinProp | protected | number | 1 | Mixin |
MyMixin4| Name | Type | Default | Description |
|---|---|---|---|
| klass | * | This is the description | |
| foo | string | Description goes here |
Mixin| Name | Type | Default | Description |
|---|---|---|---|
| klass | * | This is the description |
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
| mixinProp | protected | number | 1 |
| Name | Description | Type |
|---|---|---|
| variableExport | this is a var export | boolean |
| stringVariableExport | this is a string var export | string |
| Name | Description | Parameters | Return |
|---|---|---|---|
| functionExport | This is a function export | a: string, b: boolean | boolean |
| 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 |
FAQs
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 npm package @custom-elements-manifest/to-markdown receives a total of 770 weekly downloads. As such, @custom-elements-manifest/to-markdown popularity was classified as not popular.
We found that @custom-elements-manifest/to-markdown demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.