Docusaurus plugin component docs pages 📖

Docusaurus plugin for reusing base component mdx pages

Setup

1. Install this plugin into a UDS docusaurus docs site

npm install --save @telus-uds/docusaurus-plugin-component-docs-pages

1. Add the plugin to the docusaurus.config.js

module.exports = {
  // ...

  plugins: ['@telus-uds/docusaurus-plugin-component-docs-pages']

  // ...
}

Usage

This plugin wraps a docusaurus docs plugin with content automatically provided from the 'docs/' folder. The plugin accepts all options applicable to the docs plugin, and passes these through to the underlying docs plugin, altering only the sidebarPath to reflect the copied sidebar file.

Note 1: If you are using this as your only docs plugin and you are using the classic preset, you will need to disable docs in the preset.

Note 2: You will need to provide @theme/PropsTable @theme/Playground and @theme/LibraryInfo components in your docusaurus site for this plugin to work, you will also need to make all UDS Base components and at least an ExampleIcon available in the react live scope (see e.g. the Koodo docs site for how to do this).

module.exports = {
  // ...

  presets: [
    'classic',
    {
      docs: false,
      theme: {
        //...
      }
    }
  ],

  plugins: [
    '@telus-uds/docusaurus-plugin-component-docs-pages',
    {
      breadcrumbs: false
    }
  ]

  // ...
}

If you wish to use this plugin with a custom index page, just add a README.mdx to the directory which will contain the docs and add

slug: '/'
displayed_sidebar: generatedComponentsDocs

into the metadata.

Adding component docs

To add documentation for a component depending on a platform:

1. Add a new MDX file with id matching the component name into respective platform web, multi-platform, ios inside docs/. If the platform you need does not exist create a respective folder for it in docs/.
2. Add a sidebar file into sidebars/ with the same name as the destination folder. For eg: if shown below is your plugin options in docusaurus.config.js

;[
  '@telus-uds/docusaurus-plugin-component-docs-pages',
  {
    id: 'allium',
    path: 'components/allium',
    routeBasePath: 'components/allium',
    breadcrumbs: false
  }
]

You'll need an allium.js in sibebars with keys for each respective platform as shown below.

module.exports = {
  ios: {
    Inputs: ['ios/radio', 'ios/checkbox']
  },
  web: ['web/list', 'web/image']
}

Refer to the UDS monorepo README for details.