{"_id":"@blockquote/to-markdown","name":"@blockquote/to-markdown","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@blockquote/to-markdown","version":"0.1.0","description":"> [Individual NPM package from the following PR](https://github.com/open-wc/custom-elements-manifest/pull/221)","license":"MIT","repository":{"type":"git","url":"git+https://github.com/oscarmarina/to-markdown.git"},"author":{"name":"open-wc"},"homepage":"https://github.com/open-wc/custom-elements-manifest","types":"types/main.d.ts","bugs":{"url":"https://github.com/open-wc/custom-elements-manifest"},"main":"index.js","type":"module","scripts":{"prepare":"npm run build","build":"npm run build:browser && npm run build:cjs","build:browser":"esbuild index.js --outfile=dist/browser.js --format=esm --bundle --minify","build:cjs":"esbuild index.js --outfile=dist/index.cjs --format=cjs --bundle","test":"asdgf"},"keywords":["custom-elements","custom-elements-json","custom-elements-manifest","customelements","webcomponents","customelementsjson","customelementsmanifest","markdown","md"],"contributors":[{"name":"Pascal Schilp","email":"pascalschilp@gmail.com"},{"name":"Benny Powers","email":"web@bennypowers.com"}],"exports":{".":{"import":"./index.js","require":"./dist/index.cjs","browser":"./dist/browser.js"}},"dependencies":{"mdast-builder":"^1.1.1","mdast-util-from-markdown":"^2.0.0","mdast-util-gfm":"^3.0.0","mdast-util-to-markdown":"^2.1.0","remark-gfm":"^3.0.1","remark-stringify":"^10.0.3","unified":"^11.0.3"},"devDependencies":{"@asdgf/cli":"https://gitpkg.now.sh/thepassle/asdgf/packages/cli?master","esbuild":"^0.19.2"},"publishConfig":{"access":"public"},"gitHead":"103750818097922e6015abeb9b565bc0df693619","_id":"@blockquote/to-markdown@0.1.0","_nodeVersion":"18.17.1","_npmVersion":"9.6.7","dist":{"integrity":"sha512-c+yRl/8xJp3OzEA5uPt0Iy3fB/Xu9qs4OBb7VgGl4wd3UTaRgOX3hIVZxlE9nLWnYl/B0FYi6AYBPvIwsivyMw==","shasum":"395d663c89ac3cae1f558b0241c7e4218bc2da31","tarball":"https://registry.npmjs.org/@blockquote/to-markdown/-/to-markdown-0.1.0.tgz","fileCount":8,"unpackedSize":146203,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD61S1Nf5YDohcyBhlKSynmg67crIkGNSNQwkAU/u+WegIgJO71q6CEshjfdyn0C0+suyK3ULW7C5oRo8mbvXVto3w="}]},"_npmUser":{"name":"oscarmarina","email":"oscar7600@outlook.com"},"directories":{},"maintainers":[{"name":"oscarmarina","email":"oscar7600@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/to-markdown_0.1.0_1694359870787_0.49904905423068424"},"_hasShrinkwrap":false}},"time":{"created":"2023-09-10T15:31:10.683Z","0.1.0":"2023-09-10T15:31:10.996Z","modified":"2023-09-10T15:31:11.302Z"},"maintainers":[{"name":"oscarmarina","email":"oscar7600@outlook.com"}],"description":"> [Individual NPM package from the following PR](https://github.com/open-wc/custom-elements-manifest/pull/221)","homepage":"https://github.com/open-wc/custom-elements-manifest","keywords":["custom-elements","custom-elements-json","custom-elements-manifest","customelements","webcomponents","customelementsjson","customelementsmanifest","markdown","md"],"repository":{"type":"git","url":"git+https://github.com/oscarmarina/to-markdown.git"},"contributors":[{"name":"Pascal Schilp","email":"pascalschilp@gmail.com"},{"name":"Benny Powers","email":"web@bennypowers.com"}],"author":{"name":"open-wc"},"bugs":{"url":"https://github.com/open-wc/custom-elements-manifest"},"license":"MIT","readme":"# @blockquote/to-markdown\n\n> [Individual NPM package from the following PR](https://github.com/open-wc/custom-elements-manifest/pull/221)\n\nCustom-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).\n\nThis library takes a Custom Elements Manifest and renders it to markdown.\n\n## Usage\n\nInstall:\n```bash\nnpm i -S @blockquote/to-markdown\n```\n\nImport and use in your code:\n```js\nimport fs from 'fs';\nimport { customElementsManifestToMarkdown } from '@blockquote/to-markdown';\n\nconst manifest = JSON.parse(fs.readFileSync('./custom-elements.json', 'utf-8'));\nconst markdown = customElementsManifestToMarkdown(manifest);\n\nfs.writeFileSync('./custom-elements.md', markdown);\n```\n\n### Options\n\n| Option | Type | Default | Description |\n| ------------- | ---------------------------- | ------- | ----------- |\n| headingOffset | Integer | 0 | Offset the heading level by this number |\n| mainDescription | Boolean | true | Show description field for Class and Mixins |\n| private | `'all'\\|'details'\\|'hidden'` | `'all'` | See [Private Members](#private-members) |\n| omitDeclarations | `OptionalDeclarations[]` | [] | See [Omit Declarations](#omit-declarations) |\n| omitSections | `OptionalSections[]` | [] | See [Omit Sections](#omit-sections) |\n| classNameFilter | `string \\| (() => string)` | `'.*'` | See [Class Name Filter](#class-name-filter) |\n\n#### Private Members\n\nThe `private` option controls how private members appear in the markdown.\n- `'all'`: private members appear alongside public members according to source order\n- `'hidden'`: private members do not appear at all in markdown, but protected members do\n- `'details'`: private and protected members appear in a details disclosure widget below the table\n\n#### Omit Declarations\n\nThe `omitDeclarations` option is a `string[]` that controls which kinds of entities are rendered in the final markdown output. The four declaration types are:\n\n- mixins\n- variables\n- functions\n- exports\n\nThe following is an example config that would filter out all four declaration types:\n\n```js\ncustomElementsManifestToMarkdown(manifest, {\n omitDeclarations: ['mixins', 'variables', 'functions', 'exports' ]\n})\n```\n**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`.\n\n#### Omit Sections\n\nThe `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:\n\n- mainHeading : \"main-heading\"\n- mainDescription : \"main-description\"\n- superClass : \"super-class\"\n- fields : \"fields\"\n- methods : \"methods\"\n- staticFields : \"static-fields\"\n- staticMethods : \"static-methods\"\n- slots : \"slots\"\n- events : \"events\"\n- attributes : \"attributes\"\n- cssProperties : \"css-properties\"\n- cssParts : \"css-parts\"\n- mixins : \"main-heading\"\n\nThe following is an example config showing how to filter out a few sections:\n\n```js\ncustomElementsManifestToMarkdown(manifest, {\n // static fields and static methods tables will not be present\n // in the markdown result\n omitSections: [ 'super-class', 'static-methods', 'fields' ]\n})\n```\n\n#### Class Name Filter\nDepending 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.\n\n```js\ncustomElementsManifestToMarkdown(manifest, {\n classNameFilter: () => {\n // some logic\n return `(${prefix}-*|SuperClassExact)`; // filters out every class name that doesnt match the regex provided\n }\n})\n```\n\n## Demo\n\n```js\ncustomElementsManifestToMarkdown(manifest, {\n headingOffset: 1,\n private: 'details',\n})\n```\n
Source\n\n```json\n{\n \"schemaVersion\": \"1.0.0\",\n \"readme\": \"\",\n \"modules\": [\n {\n \"kind\": \"javascript-module\",\n \"path\": \"./fixtures/-TEST/package/my-element.js\",\n \"declarations\": [\n {\n \"kind\": \"class\",\n \"description\": \"My description\",\n \"name\": \"SuperClass\",\n \"events\": [\n {\n \"name\": \"custom-event\",\n \"type\": {\n \"text\": \"SuperCustomEvent\"\n },\n \"description\": \"this is custom\"\n }\n ],\n \"superclass\": {\n \"name\": \"LitElement\",\n \"package\": \"lit-element\"\n },\n \"members\": [\n {\n \"kind\": \"method\",\n \"name\": \"superClassMethod\",\n \"privacy\": \"public\"\n }\n ]\n },\n {\n \"kind\": \"class\",\n \"name\": \"MyElement\",\n \"cssProperties\": [\n {\n \"name\": \"--background-color\",\n \"description\": \"Controls the color of bar\"\n }\n ],\n \"cssParts\": [\n {\n \"name\": \"bar\",\n \"description\": \"Styles the color of bar\"\n }\n ],\n \"slots\": [\n {\n \"name\": \"container\",\n \"description\": \"You can put some elements here\"\n }\n ],\n \"events\": [\n {\n \"name\": \"my-event\",\n \"type\": {\n \"text\": \"Event\"\n }\n },\n {\n \"name\": \"custom-event\",\n \"type\": {\n \"text\": \"SuperCustomEvent\"\n },\n \"description\": \"this is custom\",\n \"inheritedFrom\": {\n \"name\": \"SuperClass\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n }\n ],\n \"mixins\": [\n {\n \"name\": \"LocalizeMixin\",\n \"package\": \"lion\"\n },\n {\n \"name\": \"Mixin\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n ],\n \"superclass\": {\n \"name\": \"SuperClass\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n },\n \"attributes\": [\n {\n \"name\": \"prop-1\",\n \"fieldName\": \"prop1\"\n },\n {\n \"name\": \"prop2\",\n \"fieldName\": \"prop2\"\n }\n ],\n \"members\": [\n {\n \"kind\": \"field\",\n \"name\": \"prop1\",\n \"privacy\": \"public\"\n },\n {\n \"kind\": \"field\",\n \"name\": \"prop2\",\n \"privacy\": \"public\"\n },\n {\n \"kind\": \"field\",\n \"name\": \"prop3\",\n \"privacy\": \"public\",\n \"type\": {\n \"text\": \"boolean\"\n },\n \"default\": \"true\"\n },\n {\n \"kind\": \"field\",\n \"name\": \"foo\",\n \"type\": {\n \"text\": \"string\"\n },\n \"privacy\": \"private\",\n \"description\": \"description goes here\",\n \"default\": \"'bar'\"\n },\n {\n \"kind\": \"method\",\n \"name\": \"instanceMethod\",\n \"privacy\": \"public\",\n \"description\": \"Some description of the method here\",\n \"return\": {\n \"type\": {\n \"text\": \"\"\n }\n },\n \"parameters\": [\n {\n \"name\": \"e\",\n \"type\": {\n \"text\": \"Event\"\n }\n },\n {\n \"name\": \"a\",\n \"type\": {\n \"text\": \"string\"\n },\n \"description\": \"some description\"\n }\n ]\n },\n {\n \"kind\": \"field\",\n \"name\": \"mixinProp\",\n \"type\": {\n \"text\": \"number\"\n },\n \"privacy\": \"protected\",\n \"default\": \"1\",\n \"inheritedFrom\": {\n \"name\": \"Mixin\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n },\n {\n \"kind\": \"method\",\n \"name\": \"superClassMethod\",\n \"privacy\": \"public\",\n \"inheritedFrom\": {\n \"name\": \"SuperClass\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n }\n ],\n \"tagName\": \"my-element\"\n },\n {\n \"kind\": \"variable\",\n \"name\": \"variableExport\",\n \"description\": \"this is a var export\",\n \"type\": {\n \"text\": \"boolean\"\n }\n },\n {\n \"kind\": \"variable\",\n \"name\": \"stringVariableExport\",\n \"description\": \"this is a string var export\",\n \"type\": {\n \"text\": \"string\"\n }\n },\n {\n \"kind\": \"function\",\n \"name\": \"functionExport\",\n \"description\": \"This is a function export\",\n \"return\": {\n \"type\": {\n \"text\": \"boolean\"\n }\n },\n \"parameters\": [\n {\n \"name\": \"a\",\n \"type\": {\n \"text\": \"string\"\n }\n },\n {\n \"name\": \"b\",\n \"type\": {\n \"text\": \"boolean\"\n }\n }\n ]\n },\n {\n \"kind\": \"mixin\",\n \"name\": \"MyMixin4\",\n \"parameters\": [\n {\n \"name\": \"klass\",\n \"type\": {\n \"text\": \"*\"\n },\n \"description\": \"This is the description\"\n },\n {\n \"name\": \"foo\",\n \"type\": {\n \"text\": \"string\"\n },\n \"description\": \"Description goes here\"\n }\n ]\n },\n {\n \"kind\": \"mixin\",\n \"name\": \"Mixin\",\n \"parameters\": [\n {\n \"name\": \"klass\",\n \"type\": {\n \"text\": \"*\"\n },\n \"description\": \"This is the description\"\n }\n ],\n \"members\": [\n {\n \"kind\": \"field\",\n \"name\": \"mixinProp\",\n \"type\": {\n \"text\": \"number\"\n },\n \"privacy\": \"protected\",\n \"default\": \"1\"\n }\n ]\n }\n ],\n \"exports\": [\n {\n \"kind\": \"js\",\n \"name\": \"SuperClass\",\n \"declaration\": {\n \"name\": \"SuperClass\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n },\n {\n \"kind\": \"custom-element-definition\",\n \"name\": \"my-element\",\n \"declaration\": {\n \"name\": \"MyElement\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n },\n {\n \"kind\": \"js\",\n \"name\": \"variableExport\",\n \"declaration\": {\n \"name\": \"variableExport\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n },\n {\n \"kind\": \"js\",\n \"name\": \"stringVariableExport\",\n \"declaration\": {\n \"name\": \"stringVariableExport\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n },\n {\n \"kind\": \"js\",\n \"name\": \"functionExport\",\n \"declaration\": {\n \"name\": \"functionExport\",\n \"module\": \"./fixtures/-TEST/package/my-element.js\"\n }\n }\n ]\n }\n ]\n}\n```\n\n
\n\n
Result\n\n My description\n\n ## `./fixtures/-TEST/package/my-element.js`:\n ### class: `SuperClass`\n\n #### Superclass\n\n | Name | Module | Package |\n | ---------- | ------ | ----------- |\n | LitElement | | lit-element |\n\n #### Methods\n\n | Name | Privacy | Description | Parameters | Return | Inherited From |\n | ---------------- | ------- | ----------- | ---------- | ------ | -------------- |\n | superClassMethod | public | | | | |\n\n #### Events\n\n | Name | Type | Description | Inherited From |\n | ------------ | ------------------ | -------------- | -------------- |\n | custom-event | `SuperCustomEvent` | this is custom | |\n\n
\n\n ### class: `MyElement`, `my-element`\n\n #### Superclass\n\n | Name | Module | Package |\n | ---------- | -------------------------------------- | ------- |\n | SuperClass | ./fixtures/-TEST/package/my-element.js | |\n\n #### Mixins\n\n | Name | Module | Package |\n | ------------- | -------------------------------------- | ------- |\n | LocalizeMixin | | lion |\n | Mixin | ./fixtures/-TEST/package/my-element.js | |\n\n #### Fields\n\n | Name | Privacy | Type | Default | Description | Inherited From |\n | ----- | ------- | --------- | ------- | ----------- | -------------- |\n | prop1 | public | | | | |\n | prop2 | public | | | | |\n | prop3 | public | `boolean` | `true` | | |\n\n #### Methods\n\n | Name | Privacy | Description | Parameters | Return | Inherited From |\n | ---------------- | ------- | ----------------------------------- | --------------------- | ------ | -------------- |\n | instanceMethod | public | Some description of the method here | `e: Event, a: string` | | |\n | superClassMethod | public | | | | SuperClass |\n\n #### Events\n\n | Name | Type | Description | Inherited From |\n | ------------ | ------------------ | -------------- | -------------- |\n | my-event | `Event` | | |\n | custom-event | `SuperCustomEvent` | this is custom | SuperClass |\n\n #### Attributes\n\n | Name | Field | Inherited From |\n | ------ | ----- | -------------- |\n | prop-1 | prop1 | |\n | prop2 | prop2 | |\n\n #### CSS Properties\n\n | Name | Description |\n | ------------------ | ------------------------- |\n | --background-color | Controls the color of bar |\n\n #### Slots\n\n | Name | Description |\n | --------- | ------------------------------ |\n | container | You can put some elements here |\n\n
Private API\n\n #### Fields\n\n | Name | Privacy | Type | Default | Description | Inherited From |\n | --------- | --------- | -------- | ------- | --------------------- | -------------- |\n | foo | private | `string` | `'bar'` | description goes here | |\n | mixinProp | protected | `number` | `1` | | Mixin |\n\n
\n\n
\n\n ### mixin: `MyMixin4`\n\n #### Parameters\n\n | Name | Type | Default | Description |\n | ----- | -------- | ------- | ----------------------- |\n | klass | `*` | | This is the description |\n | foo | `string` | | Description goes here |\n\n
\n\n ### mixin: `Mixin`\n\n #### Parameters\n\n | Name | Type | Default | Description |\n | ----- | ---- | ------- | ----------------------- |\n | klass | `*` | | This is the description |\n\n
Private API\n\n #### Fields\n\n | Name | Privacy | Type | Default | Description | Inherited From |\n | --------- | --------- | -------- | ------- | ----------- | -------------- |\n | mixinProp | protected | `number` | `1` | | |\n\n
\n\n
\n\n ### Variables\n\n | Name | Description | Type |\n | -------------------- | --------------------------- | --------- |\n | variableExport | this is a var export | `boolean` |\n | stringVariableExport | this is a string var export | `string` |\n\n
\n\n ### Functions\n\n | Name | Description | Parameters | Return |\n | -------------- | ------------------------- | ----------------------- | --------- |\n | functionExport | This is a function export | `a: string, b: boolean` | `boolean` |\n\n
\n\n ### Exports\n\n | Kind | Name | Declaration | Module | Package |\n | ------------------------- | -------------------- | -------------------- | -------------------------------------- | ------- |\n | js | SuperClass | SuperClass | ./fixtures/-TEST/package/my-element.js | |\n | custom-element-definition | my-element | MyElement | ./fixtures/-TEST/package/my-element.js | |\n | js | variableExport | variableExport | ./fixtures/-TEST/package/my-element.js | |\n | js | stringVariableExport | stringVariableExport | ./fixtures/-TEST/package/my-element.js | |\n | js | functionExport | functionExport | ./fixtures/-TEST/package/my-element.js | |\n\n
\n","readmeFilename":"README.md"}