🔌 cem-plugin-docsify 🔌

A custom-elements-manifest plugin that generates a docsify site for your element

Demo

Install

yarn add cem-plugin-docsify

Usage

// custom-elements-manifest.config.mjs
import docsify from 'cem-plugin-docsify';

export default {
  plugins: [
    docsify({ name: 'MyGreatCustomElement' }),
  ]
}

Configuration

The plugin comes with several built in configuration options

// custom-elements-manifest.config.mjs

docsify({
  // required
  // name of your docs page. This will appear at the top right 
  // of your docs sidebar
  name: 'MyGreatCustomElement',
  // optional. Default: ''
  // repo URL. If included a link to your repository will appear 
  // in the top right of the docs site
  repoURL: 'https://github.com/bmpickford/cem-plugin-docsify',
  // optional. Default: docs/
  // path to output doc files
  out: './docs',
  // optional. Default: false
  // if marked as true, will include an Examples link in
  // the sidebar, that will have an iframe that links
  // to './docs/storybook'. If you include this option it
  // is expected that there will be a built storybook docs
  // site in the docs folder
  includeStorybook: false,
  // optional. Default: 3000
  // docsify doesn't give many options for customizing embedded content
  // so the height needs to be static. Set to 3000 as a default but
  // this is here to modify if needed
  storybookHeight: 3000,
}),

Usage with Storybook

As seen in the demo, you can include your storybooks docs as an iFrame to easily provide tangible examples. To do this, you will need to build your storybook docs (e.g. build-storybook --docs) and set the output to docs/storybook or alternatively manually copy it across. Then apply this configuration to the plugin:

// custom-elements-manifest.config.mjs

docsify({
  name: 'MyGreatCustomElementWithStorybookDocs',
  includeStorybook: true,
}),

It is also recommended to remove any navigation and panels from the storybook docs for a better user experience. This can be configured in .storybook/manager.js

Storybook Configuration Docs

For the demo, this was the configuration used:

// .storybook/manager.js
import { addons } from '@storybook/addons';

addons.setConfig({
  showNav: false,
  showPanel: false,
  isFullscreen: true,
});

Development

Installation

yarn install

Running

This will generate the docs for the example element found in fixtures/default/sourcecode/default.js

yarn start

Run tests

yarn run test

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 Benjamin Pickford.
This project is MIT licensed.