Anatomy of a component

Components are built using html files that contain handlebar syntax. This keeps them very straight forward and easy to deal with. It also means they are not able to do any kind of advanced logic you might find in a web framework.

They are intended to provide structure and styling in places where markdown fails, not as dynamic web components like React and others.

Components are stored in a components path inside special _internal folder located at the project root.

Creating a hello component

Inside a new project create a file in project_root/_internal/components/hello.html

The component code is simple html we will use:

<h4>Hello, {{name}}</h4>

Any properties passed to the component are provided as variables to the component template and can be used with Handlebar syntax.

Now create a document at project_root/hello_page.md to use the component

# Component test
This is a test of the hello component:
<Hello name="Alice" />

Overriding existing components

Default components can also be overridden simply by redefining them in the project. Components locally defined inside _internal/components will take precedence over default ones.

For instance to override the alert component we could create project_root/_internal/alert.html with:

<div class="my-alert">
    {{#if title}}
        <div class="my-title">{{title}}</div>
    {{/if}}
    {{{children}}}
</div>

Component children

Components may have children which allows them to wrap other components or markdown blocks. The alert component above uses the children variable. A component with children is used like this:

<Alert title="My Title">
    # A header

    Some more *markdown* code
    <AnotherComponent />
</Alert>