Component description populated wrongly

[mcrodriguezb]

Configuration:
"@pxtrn/storybook-addon-docs-stencil": "^6.4.1",
"@stencil/angular-output-target": "^0.8.3",
"@storybook/addon-docs": "^7.6.15",
"@storybook/addon-essentials": "^7.6.15",
"@storybook/addon-interactions": "^7.6.15",
"@storybook/addon-links": "^7.6.15",
"@storybook/blocks": "^7.6.15",
"@storybook/builder-vite": "^7.6.15",
"@storybook/html": "^7.6.15",
"@storybook/html-vite": "^7.6.15",
"@storybook/test": "^7.6.15",
"@storybook/web-components": "^7.6.15",

main.js

import { join, dirname } from 'path';

/**
 * This function is used to resolve the absolute path of a package.
 * It is needed in projects that use Yarn PnP or are set up within a monorepo.
 */
function getAbsolutePath(value) {
  return dirname(require.resolve(join(value, 'package.json')));
}

/** @type { import('@storybook/html-vite').StorybookConfig } */
const config = {
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  typescript: {
    // Overrides the default Typescript configuration to allow multi-package components to be documented via Autodocs.
    reactDocgen: 'react-docgen',
    skipBabel: true,
    check: false,
  },
  addons: [
    getAbsolutePath('@storybook/addon-links'),
    getAbsolutePath('@storybook/addon-essentials'),
    getAbsolutePath('@storybook/addon-interactions'),
    getAbsolutePath('@pxtrn/storybook-addon-docs-stencil'),
  ],
  framework: {
    name: getAbsolutePath('@storybook/html-vite'),
    options: {},
  },
  core: {
    builder: '@storybook/builder-vite',
    disableTelemetry: true,
  },
  docs: {
    autodocs: 'tag',
    defaultName: 'Documentation',
  },
  staticDirs: ['../www/build']
};

export default config;

Preview.jsx:

// Required by webcomponents
import { defineCustomElements } from '../dist/esm/loader';

import { extractArgTypes, extractComponentDescription, setStencilDocJson } from '@pxtrn/storybook-addon-docs-stencil';
import docJson from '../custom-elements-2.json';
if(docJson) setStencilDocJson(docJson);

export const parameters = {
  controls: { hideNoControlsWarning: true }
}

// Required by webcomponents
defineCustomElements();

/** @type { import('@storybook/html').Preview } */
const preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      expanded: true,
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    docs: {
      toc: true,
      page: DocumentationTemplate,
      extractArgTypes,
      extractComponentDescription,
    }
  },
};

export default preview;

documentationTemplate.mdx:

import { Description, Meta, Title, Primary, Controls, Stories, Subtitle } from '@storybook/blocks';

<Meta isTemplate />

Title: <Title />

Subtitle: <Subtitle />

# Default implementation

Description: <Description />

Primary: <Primary />

## Inputs

The component accepts the following inputs (props):

Controls: <Controls />

---

## Additional variations

Listed below are additional variations of the component.

Stories: <Stories />

stencil.config.ts:

    {
      type: 'docs-json',
      file: 'custom-elements-2.json'
    },

The generated custom-elements-2.json generates the following entry for my component:

    {
      "filePath": "src/components/avatar/avatar.tsx",
      "encapsulation": "shadow",
      "tag": "avatar",
      "readme": "# avatar\n\n\n",
      "docs": "Generate avatars with initials from names.\nUses third party service",
      "docsTags": [],
      "usage": {},
      "props": [],
      "methods": [],
      "events": [],
      "listeners": [],
      "styles": [],
      "slots": [],
      "parts": [],
      "dependents": [],
      "dependencies": [],
      "dependencyGraph": {}
    },

From your code the description is generated using:

/**
 * @param {string} tagName - stencil component for which to extract description
 */
export const extractComponentDescription = (tagName: string): string => {
  const metaData = getMetaData(tagName, getStencilDocJson());
  return metaData && (metaData.readme || metaData.docs);
};

As because the readme has some data, it generates the wrong description as shown:

[pixtron]

Stencils docs-json output contains two properties in the component meta data:

• readme: content of readme.md in the directory where the component is located
• docs: doc block of the components class

You have two options to fix your issue:

• remove the readme.md that sits in the directory as your component sits (metaData.readme will be empty then)
• write a custom component description extractor (requires version >=6.4.2 of this addon)

//.storybook/preview.js

import { getComponentMetaData } from '@pxtrn/storybook-addon-docs-stencil';

export const parameters = {
  docs: {
    extractComponentDescription: (tagName) => {
      const metaData = getComponentMetaData(tagName);
      return metaData && (metaData.docs || metaData.readme);
    }
  }
}