Skip to content

Latest commit

 

History

History
84 lines (61 loc) · 2.86 KB

components.md

File metadata and controls

84 lines (61 loc) · 2.86 KB

Components

Table of Contents

Documentation

We're actively looking to improve our Component documentation through generating README.md files in each of our component directories. The hope is that we can add documentation around installing and using our components, in addition to covering common use-cases for each component with code examples.

If you would like to help out, there are several options to contribute component-specific documentation to carbon-components-react:

  1. Create a README.md file using this file structure, and add it to the component's story using these steps
  2. Ensure props of components are covered by Storybook knobs
  3. Ensure event handlers of components are covered by Storybook action logger

Once those steps are complete, you should be able to follow our contribution guidelines to finish making a Pull Request for your work!

File Structure

Each markdown file will tend to take on the following initial structure:

  • Component name heading
  • Brief description of the component
  • A table of contents block
  • Steps around installing and using the component
  • Details around any special cases with component prop types
  • Details around common use-cases for the components, either with embedded code or links to codesandbox.io playgrounds

You can use the template available here to help with filling out each of these steps.

Storybook README

After creating the README.md file for a component, you'll most likely want to add it to Storybook so that it shows up in the tabs for the component story. To do this, we'll use the storybook-readme add-on.

The first step will be to import the withReadme helper from storybook-readme and the README.md file in the component story by doing:

import { withReadme } from 'storybook-readme';
import readme from './README.md';

Afterwards, you can decorate each story with the withReadme helper by doing:

import { withReadme } from 'storybook-readme';
import readme from './README.md';

storiesOf('ComponentName', module).add(
  'story-title',
  withReadme(readme, () => <ComponentExample />, {
    info: {
      text: 'Information for the given story',
    },
  })
);