@telus-uds/docusaurus-theme-component-docs 📝

A Docusaurus theme exporting @theme/PropsTable, @theme/LibraryInfo and @theme/Playground components to render documentation pages, including components-base and their editable code snippets.

Setup ⚙️

1. Install this theme into a UDS Docs website powered by Docusaurus

npm install --save @telus-uds/docusaurus-theme-component-docs

2. Add the theme to the docusaurus.config.js

module.exports = {
  // ...
  themes: ['@telus-uds/docusaurus-theme-component-docs']
  // ...
}

3. Provide a UDS Compatible Theme in docusaurus.config.js

const theme = require('@telus-uds/theme-koodo')
module.exports = {
  // ...
  themeConfig: {
    // ...
    componentDocs: {
      theme
    }
  }
  // ...
}

4. Create a new file index.js under src/theme/ReactLiveScope and add the following:

import InitReactLiveScope from '@theme-init/ReactLiveScope'

// Add react-live imports you need here
const ReactLiveScope = {
  ...InitReactLiveScope
}
export default ReactLiveScope

By default, @theme-init/ReactLiveScope has the following primitives exported:

• React
• All top-level exports of React
• All top-level exports from @telus-uds/components-base

If you want to extend this list, simply reference that in ReactLiveScope object as follows:

import InitReactLiveScope from '@theme-init/ReactLiveScope'
import Cart from '@telus-uds/palette-koodo/build/web/icons/Cart'


// Add react-live imports you need here
const ReactLiveScope = {
  ...InitReactLiveScope
  ExampleIcon: Cart
}
export default ReactLiveScope

Swizzling 🌀

You can choose to swizzle other components like LibraryInfo and Playground to either enhance their functionality or pass data specific to the consumption documentation package.

LibraryInfo

By default, LibraryInfo has the following values for its props:

prop	value
library	'UDS Base'
repository	'universal-design-system'
packageName	'components-base'
packageVersion	current version of @telus-uds/components-base

But we can swizzle this component in the following way:

• Create a new file src/theme/LibraryInfo/index.jsx:

import React from 'react'
import LibraryInfo from '@theme-original/LibraryInfo'

export default function LibraryInfoWrapper(props) {
  return (
    <>
      <LibraryInfo {...props} {/* pass extra sets of props here*/} />
    </>
  )
}

Playground

We can pass a provide a UDS Compatible Theme in docusaurus.config.js but there may be situations where there is a need to provide a React provider rather than the raw theme and that is where we can swizzle Playground and pass a provider prop.

• Create a new file src/theme/Playground/index.jsx:

import React from 'react'
import Playground from '@theme-init/Playground'
import theme from '@telus-uds/theme-koodo'
import { BaseProvider } from '@telus-uds/components-base'

function KoodoProvider({ children }) {
  return <BaseProvider defaultTheme={theme}>{children}</BaseProvider>
}

export default function PlaygroundWrapper(props) {
  return (
    <>
      <Playground {...props} provider={KoodoProvider} />
    </>
  )
}

Note that if both theme (through docusaurus.config.js) and provider are provided at the same time, provider takes precedence over theme.

Also, you can choose not to wrap when you swizzle but entirely eject the default components, please check Docusaurus's documentation on swizzling to learn more.