skip to main content
skip to navigation sidebar
skip to context sidebar
A next-generation tool to create blazing-fast documentation sites
API
Blog
Tutorial
Showcase
twitter
github
Edit this page
created:3/5/2021
updated:5/17/2021
byatanasster
documentation

Document

Overview

Document is a single file containing documentation in mdx or esm format.

Properties

title (or name)

type: string
Title of the document, also used as the document unique identifier. If no route parameter is specified, the title is used to generate the document url. This is the only required field, as it is used to show the document in the menu structures.
MDX
---
title: Library/Components/Button
---
ESM
export default {
  title: 'Library/Components/Button',
}
hierarchical document titledocument title

type

type: DocType
Document type - blogs, pages, stories, and even custom ones. By default, all documents are of type story
All documents of the same type are grouped for easier search and navigation.

order

type: number
Document order used to sort between documents within the same parent menu. By default, documents are ordered by their filesystem precedence (alphabetically).
The order is used for the menu display as well as next/previous page navigation.
as an example, let's suppose you have the following 3 documents:
// first.mdx
---
title: Components/One
---


// second.mdx
---
title: Components/Two
---


// third.mdx
---
title: Components/Three
---
From the file-system order, the documents will be ordered first.mdx, second.mdx and third.mdx (ordered by their file name alphabetically). However, we can order the files manually and sort them first.mdx, third.mdx and second.mdx.
// first.mdx
---
title: Components/One
order: 0
---


// second.mdx
---
title: Components/Two
order: 2
---


// third.mdx
---
title: Components/Three
order: 1
---
custom document orderdocument order

route

type: string
If provided, will be used as the route for the document page. By default, the title in lowercase will be used as the route.
MDX
---
title: Library/Components/Spinner
route: /library/my-route
---
ESM
export default {
  title: 'Library/Components/Button',
  route: '/library/esm-route',
};
custom document routedocument route

description

type: string
Short description of the documentation page - can be an excerpt for blog posts or keywords for the full-text search. If the description is set, it will also be used for SEO purposes as the description meta tag of the page.
MDX
---
title: Library/Components/Spinner
description: this is a spinner documentation page
---
ESM
export default {
  title: 'Library/Components/Button',
  description: 'this is a button documentation page'
};
assign document descriptiondocument description

date

type: Date
Optional date when the document was created. If not assigned, the instrumentation process will use birthtime from the filesystem.
MDX
---
title: Library/Components/Spinner
date: 01/01/2020
---
ESM
export default {
  title: 'Library/Components/Button',
  date: new Date('01/01/2020'),
};

dateModified

type: Date
Optional date when the document was last modified. If not assigned, the instrumentation process will use mtime from the filesystem.
MDX
---
title: Library/Components/Spinner
dateModified: 01/01/2020
---
ESM
export default {
  title: 'Library/Components/Button',
  dateModified: new Date('01/01/2020'),
};

status

type: draft | published
If set to draft, the document will be hidden in production builds. This allows you to work on the draft version of a document without publishing it.
MDX
---
title: Library/Components/Spinner
status: draft
---
ESM
export default {
  title: 'Library/Components/Button',
  status: 'draft',
};

tags

type: string[]
List of document tags, used for cross-linking documents and the full-text search.
MDX
---
title: Library/Components/Spinner
tags:
  - documentation
  - components
---
ESM
export default {
  title: 'Library/Components/Button',
  tags: ['documentation', 'components' ],
};
custom document tagsdocument tags

author

type: string
Document author. Allows categorizing documents by author and also creating custom author's home page.
MDX
---
title: Library/Components/Spinner
author: atanasster
---
ESM
export default {
  title: 'Library/Components/Button',
  author: 'atanasster',
};

category

type: string
Category for the document, for example used by the addon-catalog to display components by category ie 'Display', 'Input' etc.
MDX
---
title: Library/Components/Spinner
category: Display
---
ESM
export default {
  title: 'Library/Components/Button',
  category: 'Display',
};
type: boolean
Whether to add a sidebar to navigate all the documents from the same document type. The default value is from the document type configuration but can also be changed at the document level.
MDX
---
title: Library/Components/Spinner
navSidebar: false
---
ESM
export default {
  title: 'Library/Components/Button',
  navSidebar: false
};
document navigation sidebardocument navSidebar

contextSidebar

type: boolean
Whether to add a context sidebar to access the sections on the current page. The default value is from the document type configuration but can also be changed at the document level.
MDX
---
title: Library/Components/Spinner
contextSidebar: false
---
ESM
export default {
  title: 'Library/Components/Button',
  contextSidebar: false,
};
document context sidebardocument context sidebar

layout.fullPage

type: `boolean
Whether the page to use the full-page theme styling (pagecontainer.full theme variant can be customized). The default value is from the document type configuration but can also be changed at the document level.
MDX
---
title: Library/Components/Spinner
fullPage: true
---
ESM
export default {
  title: 'Library/Components/Button',
  fullPage: true,
};
document full pagedocument fullPage

component

type: string | object
The component associated with the documentation page.
MDX
---
title: Library/Components/Spinner
component: Button
---
import { Button } from '../components/Button';
import { PropsTable,  ComponentSource  } from '@component-controls/blocks';


## Component Component
<ComponentSource of="." />


## Component Props
<PropsTable of="." />
ESM
import { Button } from '../components/Button';


export default {
  title: 'Library/Components/Button',
  component: Button,
};
document componentdocument component

subcomponents

type: `string[] | object[]
Multiple components option.
MDX
---
title: Library/Components/Spinner
component: Button
subcomponents:
  - Spinner
---
import { Button } from '../components/Button';
import { Spinner } from '../components/Spinner';
import { PropsTable,  ComponentSource  } from '@component-controls/blocks';


## Component Component
<ComponentSource of="." />


## Component Props
<PropsTable of="." />
ESM
import { Button } from '../components/Button';
import { Spinner } from '../components/Spinner';


export default {
  title: 'Library/Components/Button',
  component: Button,
  subcomponents: [Spinner]
};
document subcomponentsdocument subcomponents

controls

type: ComponentControls
An object of key/value pairs specifying the controls for the stories file will apply to all the stories in the file.
MDX
---
title: Library/Components/Spinner
controls: { text: 'some text' }
---
import { Playground,  Story, PropsTable  } from '@component-controls/blocks';


<Playground>
  <Story name="text-control">
    {({ text }) => (
      <div>{text}</div>
    )}
  </Story>
</Playground>


<PropsTable name="text-control" />
ESM
import React from 'react';
export default {
  title: 'Library/Components/Button',
  controls: { text: 'some text' },
};


export const textControls = ({ text }) => <div>{text}</div>;
Introduction to controls
document controlsdocument controls

decorators

type StoryRenderFn[]
An array of wrapper functions (decorators) that will be called when rendering each story.
ESM
import React from 'react';
export default {
  title: 'Library/Components/Button',
  decorators: [
    (controls, context) => {
      const { renderFn } = context;
      return (
        <div style={{ background: 'lightpink' }}>
          {renderFn(controls, context)}
        </div>
      );
    },
  ],
};


export const overview = () => <div>decorator test</div>;
document decoratorsdocument decorators

testFiles

type: `string[]
associate component test files with the document, the paths sould be relative to the document file. By default the associated test files are inferred automatically.
ESM
import { Button } from '../components/Button';


export default {
  title: 'Library/Components/Button',
  component: Button,
  testFiles: ['./Button.test.ts']
};

testCoverage

type: `string[]
associate component files to include in the coverage testing, the paths sould be relative to the document file. By default the associated coverage files are inferred automatically.
ESM
import { Button } from '../components/Button';


export default {
  title: 'Library/Components/Button',
  component: Button,
  testCoverage: ['./Button.ts', '../utils.ts']
};

testData

type: `string
associate a data-driven testing file component, the path sould be relative to the document file. By default the associated data-driven testing file is inferred automatically.
ESM
import { Button } from '../components/Button';


export default {
  title: 'Library/Components/Button',
  component: Button,
  testCoverage: ['./Button.ts', '../utils.ts']
};
Previous
Configuration/Run time
Next
Reference/Story