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`,
};

more: run-time configuration

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',
};

more: run-time configuration

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

more: writing mdx documentation

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} />

more: writing mdx stories

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" />
);

more: writing esm stories

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"
},
...

Getting started/Site generators/Storybook

Getting started/UI customization

Tutorial