category: packages
ui-docs-plugin

A webpack plugin to generate documentation made by Instructure Inc.
Installation
yarn add --dev @instructure/ui-docs-plugin
Usage
Set up a new webpack config for your documentation app, and add the plugin:
const pkg = require('./package.json')
const DocsPlugin = require('@instructure/ui-docs-plugin')
module.exports = {
entry: {
common: ['react', 'react-dom'],
'my-library': ['src'],
globals: './globals'
},
plugins: [
new DocsPlugin({
context: __dirname,
projectRoot: __dirname,
title: `${pkg.name} : ${pkg.description} (${pkg.version})`,
favicon: 'logo.png',
library: {
name: pkg.name,
version: pkg.version,
repository: pkg.repository.url,
author: pkg.author
},
files: ['src/components/*/index.js', 'docs/*.md'],
ignore: [
'**/node_modules/**',
'**/__tests__/**'
],
template: 'index.ejs'
})
]
}
Globals/Code examples
React
and ReactDOM
are both in scope for use in code examples, and a render
function is also provided
if you want to be able to control what is rendered (see below).
Anything else that you would like to be available in scope, you can define
in one of your entries (e.g. ./globals
in the example above) like:
import * as MyLibrary from './index'
Object.keys(MyLibrary).forEach((key) => {
global[key] = MyLibrary[key]
})
Themes
The plugin will generate documentation for themes that are compatible with @instructure/emotion.
You can make your own theme or import one from @instructure/ui-themes and then add them
to the plugin options:
new DocsPlugin({
themes: ['src/themes/*/index.js']
})
Codepen links
To display a link to open examples in codepen, add the codepen API data to the plugin options:
new DocsPlugin({
library: {
codepen: {
js_external: [
`${pkg.homepage}common.js`,
`${pkg.homepage}instructure-ui.js`,
`${pkg.homepage}globals.js`
].join(';')
}
}
})
Documenting a mono-repo
If you need to document multiple packages in the same repo, configure the library as follows:
new DocsPlugin({
library: {
...
packages: 'packages',
scope: '@instructure'
}
})
Customizing generated paths and IDS
You can add custom functions to the plugin config to change how document identifiers, titles and
paths to JS modules are generated:
module.exports = {
...
document: {
identifier: function (docData, context) {
...
},
title: function (docData, context) {
...
},
srcPath: function (docPath, context) {
...
},
srcUrl: function (docPath, context) {
...
},
requirePath: function (docPath, context) {
...
},
esPath: function (docPath, context) {
...
}
}
}
Writing documentation
You can write documentation in markdown files or in code comment blocks in your source files.
Documentation meta data:
You can configure optional meta data about a document with YAML front matter inside your markdown content.
---
example: false
---
---
category: guides/contributing
id: code_of_conduct
order: 3
title: Code of Conduct
---
The front matter must be the first content in the markdown file or comment block.
Note: categories can be nested via the /
delimiter.
README files
In README files you can add the meta data:
---
example: false
---
---
describes: MyComponent
---
To have the README file content serve as the description for the resource with the id 'MyComponent'. Usually this will
be the index.js
file in that directory.
Documents with the describes
meta data won't show up in the documentation navigation.
Code examples
If you would like to display an example of a rendered component along with the code example, you can include a
markdown code block like:
```js
---
example: true
---
<Button>Click Me</Button>
```
If you would like to display the component on a dark background or dark checkerboard, you can add some extra data as
yaml front matter to your code block:
```js
---
example: true
background: 'checkerboard-inverse'
---
<Button color="primary" withBackground={false}>Click Me</Button>
```
If you would like to show a more complex code example, you can control what's rendered yourself with the following
configuration:
```js
---
render: false
example: true
---
const MyButton = () => <Button>Click Me</Button>
render(MyButton)
```
To make the code editor read-only you can configure the code block as:
```js
---
readOnly: true
---
<Button>Click Me</Button>
```
Development
From the root of the instructure-ui
repo: