Documentation Files

All components should be documented in component-specific Markdown documentation files. If a component has variations (see Data Files and Demo Folders), they should also be documented in separate variation-specific documentation files.

Documentation files should have the following sections:

1. Front Matter
2. Description
3. Properties
4. Notes
5. Variations
6. Less variables

The only compulsory section is the Front Matter section. Other sections should be added where applicable.

Front matter

All documentation files must begin a block of YAML set between triple-dashed lines.

Example:

---
title: Panel
state: complete
---

This block is called front matter, and it is used in building the component library website.

Key	Allowed values
title	Human readable component or component variation name
state	inprogress, inreview, complete

Description

Description of the component or component variation. Component variations may leave this section out if the variation name is explanatory enough.

Properties

All properties ($this->render() parameters) exposed by the component should be documented in a table with columns for parameter name, type and possible default value.

Example:

Property	Type	Default value
attributes	array
collapsed	boolean	true
collapseId	string
content	string
heading	string
headingId	string
headingLevel	integer
headingTag	boolean	true

Notes

This section should contain notes on using the properties and anything else that is good to know about the functionality of the component.

Example:

Setting collapseId, heading and headingId will make the panel collapsible.

collapsed has no effect unless the panel is collapsible.

ARIA role and aria-level attributes will be added to the heading div if a headingLevel is set and headingTag is set to false.

Variations

Possible component variations should be documented in this section.

Example:

Class	Description
finna-panel-default	Default variation
finna-panel-borderless	Borderless variation

Less variables

All global and component-specific Less variables used by the component should be documented in this section.