@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

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