A next-generation tool to create blazing-fast documentation sites
API
created:12/23/2021
updated:12/23/2021

Documentation site

In this tutorial, we assume you have already selected and set up a static site generator (SSG) for your documentation site

Configuration folder

Create a new folder called .config (or any other name that you used in the SSG setup above) inside your project's home directory:

Build-time configuration

In the .config folder, create a buildtime.js file.
In this file, enter the paths (e.g. .mdx and/or .tsx) we want to search for the documentation files:

.config/buildtime.js

module.exports = {
stories: ["../src/docs/*.mdx", "../src/components/**/*.docs.tsx"],
siteUrl: `https://component-controls-gatsby.netlify.app`,
};

Run-time configuration

In .config, create a runtime.js file and change some of the site's meta information:

.config/runtime.js

module.exports = {
title: `awLib`,
description: `Some description meta.`,
author: 'my name',
};

Documentation folder

Create a folder to store your documentation files (the same as specified in the .config/buildtime.js file above):
mkdir src && mkdir src/docs

MDX documentation file

src/docs/first-page.mdx

---
title: First Page
---
# My first doc page
other markdown

MDX "story" file

We built a simple component for this turial VariantButton.

src/docs/first-story.mdx

---
title: First Story
---
import { VariantButton } from '../components/VariantButton';
import {
Playground,
Story,
PropsTable,
ComponentSource,
StorySource,
} from '@component-controls/blocks';
# My first doc story
<ComponentSource of={VariantButton} title="Component source" />
<Playground description="VariantButton story">
<Story name="simple">
<Button>click me</Button>
</Story>
</Playground>
<StorySource id="." />
<PropsTable of={Button} />

ESM "story" file

Using the [VariantButton] example, we will create a new documentation page for our component. It is a recommended practice to place you components in their own folder and to also create their documentation, test files etc. in the same folder.

src/components/VariantButton/VariantButton.docs.tsx

import React from 'react';
import { Document, Example } from '@component-controls/core';
import { VariantButton, VariantButtonProps } from './VariantButton';
export default {
title: 'VariantButton',
component: VariantButton,
} as Document;
export const overview: Example<VariantButtonProps> = props => (
<VariantButton {...props} />
);
overview.controls = {
text: 'Button',
icon: 'search',
};
export const primary: Example = () => (
<VariantButton variant="primary" text="Primary" />
);
export const accent: Example = () => (
<VariantButton variant="accent" text="Accent" />
);
export const disabled: Example = () => (
<VariantButton variant="disabled" text="Disabled" />
);
export const success: Example = () => (
<VariantButton variant="success" text="Success" />
);
export const error: Example = () => (
<VariantButton variant="error" text="Error" />
);
export const warning: Example = () => (
<VariantButton variant="error" text="Warning" />
);

Add automatic tests

We provide a command-line tool that will automatically generate snapshot tests for your new documentation site.

Project repository

If your project is public, you can automatically display a git link on all documentation pages. For example, check out the "Edit this page" section here.
Displaying the git link is simple. Just add the repository's information in package.json:

package.json

...
"repository": {
"type": "git",
"url": "https://github.com/ccontrols/gatsby-controls-starter.git"
},
...