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

Below, we go over how to add a component-controls documentation site to new Nextjs projects, existing React projects, and existing Nextjs projects.

You can find a git repo and a live site.

Clone starter

The easiest way to get started is to clone the nextjs-controls-starter project

git clone https://github.com/ccontrols/nextjs-controls-starter my-nextjs-project

New project

If you want to create and configure a Nextjs documentation site from scratch instead of cloning the starter repo, the following steps are required:

mkdir my-nextjs-project && cd my-nextjs-project

Initialize the project:

yarn init

Add nextjs and react packages:

yarn add next react react-dom

Optional (but recommended), add typescript dependencies

yarn add --dev typescript @types/react @types/node

package.json

"scripts": {
"build": "next build && next export",
"start": "next",
"start-server": "next build && next start"
},

The remaining steps are the same as for existing Nextjs projects.

Existing (non-Nextjs) React project

All you have to do is add Nextjs as a dependency:

yarn add next

Then follow the steps for existing Nextjs projects.

Existing Nextjs project

Add component-controls

yarn add @component-controls/nextjs-plugin

Enable component-controls

The default options will configure component-controls to work with react apps, with react-docgen for prop-types and react-docgen-typescript for typescript props information

next.config.js

const withStories = require('@component-controls/nextjs-plugin/build');
module.exports = withStories({ configPath: '.config', ....other options });

Create content pages

Create a pages folder

mkdir pages

Application home

Create a new or edit index.tsx or index.js file in the pages folder:

view source...

pages/index.tsx

import React, { FC } from 'react';
import { GetStaticProps } from 'next';
import { DocType, defDocType } from '@component-controls/core';
import { DocPage } from '@component-controls/app';
import { Layout, store, getIndexPage } from '@component-controls/nextjs-plugin';
interface PageListProps {
type: DocType;
docId?: string;
storyId?: string;
}
const HomePage: FC<PageListProps> = ({ type = defDocType, docId, storyId }) => {
return (
<Layout docId={docId} storyId={storyId}>
<DocPage type={type} />
</Layout>
);
};
export const getStaticProps: GetStaticProps = async () => {
const homePage = getIndexPage(store);
const { docId = null, type = null, storyId = null } = homePage;
return { props: { docId, type, storyId } };
};
export default HomePage;

Document type home

Create a new [doctype].tsx or [doctype].js file in the pages folder:

view source...

pages/[doctype].tsx

import React, { FC } from 'react';
import { GetStaticProps, GetStaticPaths } from 'next';
import { DocType, defDocType } from '@component-controls/core';
import { DocumentHomePage } from '@component-controls/app';
import {
Layout,
store,
getHomePagesPaths,
getDocHomePage,
} from '@component-controls/nextjs-plugin';
interface PageListProps {
type: DocType;
docId?: string;
storyId?: string;
}
const DocHomeTemplate: FC<PageListProps> = ({
type = defDocType,
docId,
storyId,
}) => {
return (
<Layout docId={docId} storyId={storyId}>
<DocumentHomePage type={type} />
</Layout>
);
};
export const getStaticPaths: GetStaticPaths = async () => {
return { paths: getHomePagesPaths(store), fallback: false };
};
export const getStaticProps: GetStaticProps = async ({ params }) => {
const { doctype: basepath } = params as { doctype: string };
const page = getDocHomePage(store, basepath);
const { type = null, docId = null, storyId = null } = page || {};
return { props: { docId, storyId, type } };
};
export default DocHomeTemplate;

Document and Story pages

Create a new sub-folder [doctype] in the pages folder, and in it a new [...docid].tsx or [...docid].js file:

Create a pages folder

mkdir pages/[doctype]
view source...

pages/[doctype]/[...docid].tsx

import React, { FC } from 'react';
import { GetStaticProps, GetStaticPaths } from 'next';
import { DocPage } from '@component-controls/app';
import { DocType } from '@component-controls/core';
import {
Layout,
store,
getDocPagesPaths,
getDocPage,
} from '@component-controls/nextjs-plugin';
interface DocPageProps {
docId?: string;
storyId?: string;
type: DocType;
activeTab?: string;
category?: string;
}
const DocPageTemplate: FC<DocPageProps> = ({
docId,
storyId,
type,
category,
activeTab,
}) => {
return (
<Layout docId={docId} storyId={storyId} activeTab={activeTab}>
<DocPage type={type} category={category} />
</Layout>
);
};
export const getStaticPaths: GetStaticPaths = async () => {
return { paths: getDocPagesPaths(store), fallback: false };
};
export const getStaticProps: GetStaticProps = async ({ params }) => {
const { doctype, docid } = params as { doctype: string; docid: string[] };
const page = getDocPage(store, doctype, docid);
const {
type = null,
docId = null,
storyId = null,
category = null,
activeTab = null,
} = page || {};
return { props: { docId, type, storyId, category, activeTab } };
};
export default DocPageTemplate;

Create your documentation site

Check our create a documentation site tutorial