Skip to main content

Templates

C2M is fully customizable through the Handlebars template engine.

You can see the list of all available templates here, or you can generate your own template, see below how to do it.

How to create a custom template​

First thing to do is create the file, let's say the name is my-template.hbs.

You can copy one of the available templates, which are in this directory, and change it the way you want. Or you can start one from scratch, the limit is your imagination.

The new template has to follow the Handlebars formatting. See the topics below to understand the native features of C2M.

After the template is ready, just define the path to your template:

npx components-to-markdown@latest -w
  -o ./output-path \
  --template ./my-template.hbs \
  ./components-path

Parameters​

All information collected from the components is loaded and normalized in parameters so that they can be used easily and structured in the template. See all parameters in the API documentation.

Helpers​

In the template, you can use:

Built-in Helpers​

headingId​

In Docusaurus, each heading has an ID that can be automatically generated or explicitly specified. The headingId helper generates an explicit heading id from the heading text.

Example:

template.hbs
## {{name}} {{headingId name}}

The result:

hello.md
## MyComponent {#mycomponent}

markdownToJSX​

The markdownToJSX helper converts a markdown string to JSX. It's useful when you want to include some text, like a component description for example, inside JSX (or HTML) elements.

All markdown supports HTML, MDX in addition to HTML also supports JSX. However, you can't mix the two within the same block, so this helper will help to keep only one language in case you want to use HTML or MDX with a markdown formatted input.

Example:

Component doc
/**
 * MyComponent with **bold** and *italic* text, and `inline code`.
 */
function MyComponent() {
template.hbs
<div class='my-custom-element'>
  {{markdownToJSX description}}
</div>

The result:

MyComponent.md
<div class="my-custom-element">
  MyComponent with <strong>bold</strong> and <em>italic</em> text, and
  <code>inline code</code>.
</div>

Custom helpers​

You can define your own helpers using the helpers property of the configuration. For example:

import { componentsToMarkdown } from 'components-to-markdown';

componentsToMarkdown({
  helpers: [
    {
      name: 'myCustomHelper',
      helper: function (text) {
        return `${text.toUpperCase()}!`;
      },
    },
  ],
});

In the template use it as a normal helper:

template.hbs
## {{myCustomHelper 'MyComponent'}}

The result would be:

MyComponent.md
## MYCOMPONENT!

Hooks​

C2M also provides a feature called hook, which are functions you can define to change its default behavior.