Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oscarmarina/to-markdown
https://github.com/oscarmarina/to-markdown
Last synced: 11 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/oscarmarina/to-markdown
- Owner: oscarmarina
- Created: 2023-09-10T15:07:04.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-10T15:30:49.000Z (about 1 year ago)
- Last Synced: 2024-10-13T11:07:29.820Z (26 days ago)
- Language: JavaScript
- Size: 40 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @blockquote/to-markdown
> [Individual NPM package from the following PR](https://github.com/open-wc/custom-elements-manifest/pull/221)
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](https://github.com/webcomponents/custom-elements-manifest).
This library takes a Custom Elements Manifest and renders it to markdown.
## Usage
Install:
```bash
npm i -S @blockquote/to-markdown
```
Import and use in your code:
```js
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](#private-members) |
| omitDeclarations | `OptionalDeclarations[]` | [] | See [Omit Declarations](#omit-declarations) |
| omitSections | `OptionalSections[]` | [] | See [Omit Sections](#omit-sections) |
| classNameFilter | `string \| (() => string)` | `'.*'` | See [Class Name Filter](#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:
```js
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:
```js
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.
```js
customElementsManifestToMarkdown(manifest, {
classNameFilter: () => {
// some logic
return `(${prefix}-*|SuperClassExact)`; // filters out every class name that doesnt match the regex provided
}
})
```
## Demo
```js
customElementsManifestToMarkdown(manifest, {
headingOffset: 1,
private: 'details',
})
```
Source
```json
{
"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 | 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 | |