Doc Templates

Environments render documentation based on the documentation template configured for that environment.

The documentation template must be wrapped in a root function which, in order for Hot Module Reloading (HMR) to work well, contains only a render function to which you supply a single react component (example below). It is this wrapper function, exposed as a module (export default WrapperFunction) that you provide the environment in order to override the default documentation.

This Root function is provided with the following inputs or props, which can be utilised in whatever way you see fit to render component documentation:

export type DocsRootProps = {
  componentId: string;
  docs: Docs | undefined;
  compositions: any;
  context: RenderingContext;
};
CopiedCopy

Template root wrapper example:

// ...
export default function MyDocsRoot({ componentId, docs, compositions, context }: DocsRootProps) {
  ReactDOM.render(
    <MyDocsApp // your documentation template
      compositions={compositions}
      docs={docs}
      componentId={componentId}
      renderingContext={context}
    />,
    document.getElementById('root')
  );
}

export default MyDocsRoot;
CopiedCopy
note

For Hot Module Reload reasons, it's important to ensure that the root Docs app, as the entry to your docs, is not a react component and renders a single component - as in the above example, with only the MyDocsApp component being rendered, and passed the relevant inputs. MyDocsApp itself can be composed of as many components as required to fully implement your docs template.

The MyDocsApp can contain any react code you want, and can use or not use any of the input data it wants/needs. You can render anything you like inside your docs template, visualising the data supplied, and/or other data you can fetch from the many APIs bit's aspects expose.

Input Data

The following data is provided in the props passed to your Docs template Root function:

  1. compositions - An array of the compositions created for the component. These are always in the form of a react component.
  2. docs - the docs object contains the documentation you added to the component in a docs.md/x files
  3. componentId - the full id of the component
  4. renderingContext - this object contains a get() function to obtain the rendering context of the relevant env - essentially the wrapper 'providers' supplied by the env for component compositions. See the Apply Providers function logic for how this is used.

Default Documentation Template

All Bit's core envs contain a default template which renders the following 3 sections:

  1. Documentation (the content of the *.docs.md/x file in your component)
  2. Compositions as a gallery
  3. Properties table outlining the component schema

Core docs templates also contain some wrapper components for applying our default docs theme and the providers the environment has injected (such as composition wrappers, etc).

  1. Docs App - wraps the Icon Fonts and our own docs block styling
  2. Apply Providers - applies any providers that are added via the component's environment in the env's preview.runtime file.

Doc templates display doc files content using a specific layout. This layout may also be enriched with additional data provided by the template. Templates are set by Envs to provide doc layout that best fits the Envs components.

Setting a doc template

To set your own template, create a custom Env and implement the relevant override function for the core env being customized.

Override React/React-Native Docs Template
Override Angular Docs Template - documentation coming soon

For example:

// ...

static async provider([react, envs]: [ReactMain, EnvsMain]) {
  // ...
  const MyCustomEnv = react.compose([
    // ...
    react.overrideDocsTemplate(require.resolve('./docs')) // path to the file your docs template Root Function is default exported from
    // ...
  ])

}
CopiedCopy

See the DevServer service to learn how customize the bundling of the docs in development.

See the Bundler service to learn how to customize the bundling of the docs for distribution.