Components

Components run on the client, and are a way to include JavaScript interactivity into Markdown documents in a way that sparks joy.

This is a component:

Clicking the button for your favourite editor should display a message confirming that it is indeed the best editor.

A component is activated in (made available to) the .ucc file by including a @component directive:

@component best-editor

Components must be placed in /services/http/kondo/components, and the component name must only use unaccented latin letters, digits, and -. You can include as many @component directives as necessary. The above component is found at:

/services/http/kondo/components/best-editor.vue

Components are implemented using Vue 2, but more on that later.

Once you include a component in a document, you can use the fact that Markdown allows you to directly include HTML elements to insert the component. For example, the above component was included with:

<best-editor prompt="Click one of these buttons!">
</best-editor>

It is also possible to include components at the inline level, not just as blocks. Using the following:

> Clicking this number (<example></example>) or this 
> one (<example></example>) will make them increase.

Results in:

Clicking this number () or this one () will make them increase.

Also note that each component has an independent state, and that the page can have many instances of the same component.

The component .vue file itself contains three sections, working similarly to Vue 2 Single File Components. The first is the <template> section, which is standard HTML with additional extensions that Vue adds:

<template>
    <span class="counter" @click="count++">{{ '{' }}{{ '{' }} count }}</span>
</template>

The second part contains just the JavaScript for the component, which is best left to the Vue guide to explain:

<script>
module.exports = {
    data() {
        return { count: 1 }
    }
};
</script>

The third part is a set of CSS styles:

<style>
.counter
{
    background-color: rgba(255, 255, 255, 0.4);
    padding: 4px;
    cursor: pointer;
}
</style>

Vue is a very popular framework, and there are many resources such as Awesome Vue to explore it.

Limitations

Normally when you use Vue, you're using something like Vite—and the set of tools it calls upon—to compile .vue files into some giant ball of JavaScript that even the most primitive, obsolete browsers can render. Since we don't want kondo to have any large dependencies, Vue is deployed by Kondo without running any tooling at all (that this is possible is one of the impressive features of Vue, compared to other frameworks). This means there are a few limitations to keep in mind:

• Vue 2 is being used, not Vue 3, which has quite a few syntax differences.
• The .vue files are not actually compiled by the Vue SFC compiler, they are instead parsed in kondo/components.py which does not support scoped CSS (<style scoped>) or TypeScript.
• The JavaScript isn't run through Babel to support older browsers, so use tools like caniuse.com to make sure you aren't using JavaScript features that aren't widely supported.

Debugging

When you add the first @component directive, the production version of Vue is automatically included. Adding the following directive switches to using the debug version:

@debug