Notes

It's often very important to be able to clearly document the individual components in a system. You might want to include rationale about a component's structure, add notes on how and where it can be used or include any other useful information for the people who may be using the component library.

Whilst Fractal lets you create rich standalone documentation pages, often it makes more sense for individual components' documentation to live alongside the component itself. There are a few ways you can do this in Fractal:

The README.md file

Components and variants can include notes in a markdown file (filename is case-insensitive), for example: README.md, readme.md, <component-name>.readme.md, or <component-name>--<variant-name>.readme.md file beside the component template file:

├── components
│   ├── blockquote
│   │   ├── blockquote.hbs
│   │   └── README.md # or readme.md
|   ├── button.hbs
|   ├── button.readme.md
|   ├── button--primary.hbs
|   ├── button--primary.readme.md   

As noted above, for compound component blockquote, its notes can still be written in a README.md file.

If present, the contents of the README file will be run through the full Fractal documentation parser before being displayed to the user in places such as the web UI. That means that the file will be rendered with the documentation template engine (Handlebars by default) before being passed through a Markdown parser.

This means you can do almost anything that you can do in standard documentation pages in your component-specific documentation, including creating 'dynamic' documentation that is tied tightly to the component's templates or context data.

WARNING

Fractal does not support the use of YAML front-matter in README.md files.

Notes in config files

If you do not want to include a README.md file, you can also specify component notes in a configuration file using the notes property:

// my-component.config.json
{
    "notes": "These are some **notes** about the component"
}

Notes created in this format will also be run through the template engine and Markdown parser before display.