Component Docs
[![Code Coverage][coverage-badge]][coverage]
Goals
- Simple API with minimal configuration
- Fully static, deployable on GitHub pages
- Both server + client routing
- Optimized for mobile screens
- Improved DX with useful features like hot reload
- Supports rendering React Components as well as markdown and MDX files
- Support including markdown from a file reference in markdown files
Installation
yarn add --dev component-docs
Configuration
You can specify the configuration using a JavaScript, JSON or YAML file. This can be in form of:
component-docs.config.js
JS file exporting the object (recommended).component-docs
property in apackage.json
file..component-docs
file with JSON or YAML syntax..component-docs.json
,.component-docs.yaml
,.component-docs.yml
, or.component-docs.js
file.
Example component-docs.config.js
:
module.exports = {
port: 1234,
pages: [
{ type: 'md', file: path.resolve(__dirname, 'index.md') },
{ type: 'md', file: path.resolve(__dirname, 'guide.md') },
],
};
Options
The configuration object can contain the following properties:
pages
(required): An array of items or a function returning an array of items to show as pagesroot
: The root directory for the project.output
: Output directory for generated files.assets
: Directories containing the asset files.styles
: Additional CSS files to include in the HTML.scripts
: Additional JS files to include in the HTML.logo
: Logo image from assets to show in sidebar.colors
: Colors to use in the page. This is implemented using CSS variables and falls back to default grey colors on IE.primary
: Primary color used in highlighted items, links etc.
github
: Link to github folder to show edit button.port
: Port to run the server on.open
: Whether to open the browser window.
Format for pages
Each item in your pages array can contain 3 properties:
type
(required):md
for markdown files,mdx
for MDX files,component
to extract component documentation usingreact-docgen
orcustom
to render provided file as a React component.file
(required): absolute path to the file.group
: A heading to group this item under. By default, grouping is done for component documentation pages with a dot (.
) in the name. You can passnull
here to disable this behavior.
CLI
To serve docs with your config, run:
yarn component-docs serve
You can also specify a glob of files to use as pages:
yarn component-docs serve "*.{md,mdx}"
The CLI accepts several arguments. See --help
for details.
API
If you want to use component-docs
programmatically, you can use the exported serve
and build
functions.
Example:
import path from 'path';
import { build } from 'component-docs';
const pages = [
{ type: 'md', file: '../docs/Get Started.md' },
{ type: 'mdx', file: '../docs/Contributing.mdx' },
{ type: 'separator' },
{ type: 'component', file: '../src/Button.js', }
{ type: 'component', file: '../src/Calendar.js' },
];
build({
pages: pages.map(page => ({ ...page, file: path.join(__dirname, page.file) })),
output: path.join(__dirname, 'pages'),
});
The serve
and build
functions accept the same options object that's used for the configuration file. If a configuration file already exists, the options will be merged.
Extras
MDX support
MDX is a format that lets you seamlessly use JSX in your Markdown documents. This allows you to write your documentation using markdown and have interactive React components inside the documentation.
File references in Markdown
You can refer to another markdown file and the content of the markdown file will be inlined. When a line starts with a /
and ends in .md
, we recognize it as a file reference.
For example:
## Some heading
/../Details.md
Some more text here.
Here, there is a reference to the ../Details.md
file. Its content will be inlined into the markdown file where it's referenced.
Specifying metadata
Documents can specify metadata such as the page title
, description
and link
to use. The methods vary according to the type of the document.
For markdown documents, metadata can be specified in the YAML front-matter:
---
title: Home
description: This is the homepage.
link: index
---
For MDX and React documents, metadata can be exported as a named export named meta
:
export const meta = {
title: 'Home',
description: 'This is the homepage.',
link: 'index',
};
Example
component-docs
is used for react-native-paper