A next-generation tool to create blazing-fast documentation sites
API
created:6/29/2020
,
updated:12/28/2020

File

The build-time configuration file is located in the configuration-path folder. This file runs under a nodejs process and some functionlity is limited (e.g. typescript). Possible names for the file:

  • buildtime.js
  • build.js
  • main.js

Configurable Fields

NameTypeDescription
categoriesDocType[]page types that are considered as categories fields as well
pagesPagesOnlyRoutesbase url path for API documentation pages.
stories or filesstringstring[]
ignorestring[]files to ignore while building the site, in lowercase. Defaults to ['readme.md', 'changelog.md', 'code_of_conduct.md', 'contributing.md', 'license.md',]
webpack or finalWebpackWebpackConfigcustom webpack configuration setup. One or the other will be used
siteRootstringthe site base url, by default the site starts at /
siteMap{ pages?: { home: SitemapConfigPage; index: SitemapConfigPage; doc: SitemapConfigPage;};if false, disable automatic sitemap generation or specify priority of pages
siteUrlstringDeployed site url, also used for auto generated sitemap.
loaders'css-loader'/'postcss-loader' /

categories

by default, author and tags are category page types the following example adds a language category

.config/buildtime.js

module.exports = {
categories: ['author', 'tags', 'language']
pages: {
language: {
basePath: 'lang/',
},
},
}

pages

the following example sets up custom page types and routes

  • api is replacing standard docs and adds a new custom tab test
  • tutorial is a new page type

.config/buildtime.js

module.exports = {
pages: {
story: {
basePath: 'api/',
tabs: {
...defaultBuildConfig.pages.story.tabs,
test: '@component-controls/pages/TestingPage',
},
},
tutorial: {
basePath: 'tutorial/',
},
},
};

stories

the paths are relative to the config folder where the buildtime.js configuration file is located.

the following example will search for documents in the ../src/docs folder

.config/buildtime.js

module.exports = {
stories: ['../src/docs/*.@(mdx|tsx)'],
};

siteRoot

this option allows to install the component-controls site under a custom sub-folder on a site

the following example will prefix all paths with /docs/

.config/buildtime.js

module.exports = {
siteRoot: '/docs/',
};

siteMap

the following example will disable automatic generating the sitemap.xml file.

.config/buildtime.js

module.exports = {
siteMap: false,
};

loaders

the following example creates options to use modules for CSS class names

.config/buildtime.js

module.exports = {
loaders: {
'css-loader': {
modules: {
localIdentName: '[name].[local].[hash]',
},
},
},
};