A next-generation tool to create blazing-fast documentation sites
API
created:7/29/2020
,
updated:2/21/2021

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

Assuming you have a Button component, you can write stories(examples) for it.

(If you don't have a Button component, we built a simple one you can copy here.)

src/docs/first-story.mdx

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

more: writing mdx stories

ESM "story" file

Assuming you have a Button component, you can write stories(examples) for it.

(If you don't have a Button component, we built a simple one you can copy here.)

src/docs/first-story.stories.tsx

import React from 'react';
import { Button } from '../components/Button';
export default {
title: 'ES Story',
component: Button,
};
export const overview = () => <Button>click me</Button>;

more: writing esm stories

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