[Feature Request: to-markdown] support `--features` flag

[michaelwarren1106]

Hi all-

I took a look through the docs and didnt see anything like this, so I figured I'd request it.

I think it would be really useful to support a option/flag in the to-markdown package and the CEM plugin for markdown that lets consumers decide which sections to include in the final MD output, similar to the --features option in the wca analyzer tool so that the final markdown output could be customized according to use case.

My first question is whether or not there's currently a way to do this, as I'm trying to use the generated markdown for technical docs for my design system, but Im not a fan of the file info sections that the markdown lib currently creates. Its making me flip flop about deciding which analyzer/markdown tool to use, this one or wca. I predict that wca may end up deprecated as the push for switching to the new manifest.json format is pushed forward, so i'd rather use this one, but I definitely would like to be able to customize the output a bit more

My second question is how similar in implementations are the two analyzers? is it a case of porting the feature over, or is there more to it because the implementations are drastically different?

I would be down to help if i can, but i'm not that familiar with ASTs and such.

Edit:

Looking through, could it be as simple as how the returned array in makeModuleDoc gets filled. https://github.com/open-wc/custom-elements-manifest/blob/master/packages/to-markdown/index.js#L103

Thanks!

[thepassle]

Currently to-markdown doesnt support this, no. It is something we've considered adding before, but we havent got there yet.

What you can do is create a custom plugin, modify/filter the customElementsManifest object to filter out what you want/dont want, and then pass it to customElementsManifestToMarkdown. e.g.:

import { customElementsManifestToMarkdown } from '@custom-elements-manifest/to-markdown';

export function markdown() {
  return {
    name: 'markdown',
    packageLinkPhase({customElementsManifest}) {
      // mutate the cem
      customElementsManifest?.modules?.forEach(mod => {
        mod.declarations = mod?.declarations?.filter(({kind}) => kind === 'class');
      });

      // pass it to markdown
      const md = customElementsManifestToMarkdown(customElementsManifest);

      // write to file somehow
    }
  }
}

I would be down to help if i can, but i'm not that familiar with ASTs and such.

I do agree that the functional approach and all the AST-y stuff isn't really inviting or welcoming for contributions, which is a bit of a shame..

[michaelwarren1106]

I started working on a PR, relevant code starts here: https://github.com/michaelwarren1106/custom-elements-manifest/blob/master/packages/to-markdown/index.js#L109

but your comment about the plugin makes me think that I might need to change approach a bit? would you prefer I open a WIP PR for feedback, or are my local repo changes good enough for you to get an idea of where i am headed?

I went down the road of having a config object that has booleans for each section/type of info that can be removed, so that, when false the section isnt rendered. The only struggle Im having right now is telling the difference between the "main class" and super classes, because currently the manifest schema doesnt seem to mark them differently. I have an option currently to remove superClass sections in case those aren't relevant for whatever reason, but the way the nodes get rendered leaves me a bit confused on the best way to check to see if the node i'm about to render belongs to a super class, since i only have kind === 'class' and the superClass property.

[thepassle]

PR is also fine, in that case i'll defer to @bennypowers

[michaelwarren1106]

question: in the manifest.json will the last kind === 'class' declaration always be the "root class"?

[thepassle]

no

[bennypowers]

yeah sounds like a good feature, please open a pr

[michaelwarren1106]

will do! i started down one path but i think i have a better idea, so i’m gonna start over.

was struggling with how to remove superclasses but i think i have a config approach that’ll be flexible enough to allow all kinds of final documentation use cases

[michaelwarren1106]

https://github.com/open-wc/custom-elements-manifest/pull/139