File Format #

The file format of Macaron files (.macaron) is based on HTML and CSS. The benefits are:

• Easy to read and modify for humans.
• Easy to parse and emit programmatically.
• Easy to "eject" - since the data is represented in plain HTML/CSS, you can migrate from Macaron to plain HTML/CSS or other frameworks with little effort.

Edit .macaron files in text editor (VS Code) #

If you have installed the VS Code extension for Macaron, VS Code opens .macaron files in the visual editor by default.

When you want to edit a .macaron file by hand in the text editor, right-click on the file and select Open With... and select Text Editor.

Example File #

<!-- imports to external Web Components: -->
<!-- may be a link to a CDN delivered library -->
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/<some package>..."
></script>
<!-- or a local file -->
<script type="module" src="./external-components.js"></script>

<!-- Global CSS variables --->
<style>
  :root {
    --my-global-text-color: #111;
    --my-card-title-color: red;
  }
</style>

<!-- Components --->
<macaron-component name="my-card">
  <!-- Variants -->
  <macaron-variant x="0" y="0"></macaron-variant>
  <macaron-variant x="200" y="0" selector=":hover"></macaron-variant>
  <macaron-variant x="400" y="0" media="(max-width: 768px)"></macaron-variant>

  <!-- DOM structure -->
  <template>
    <h1 id="title">Hello, world!</h1>
    <img id="image" />
    <p id="text"><slot></slot></p>
  </template>

  <!-- Styles -->
  <style>
    #title {
      font-size: 24px;
      color: var(--my-card-title-color);
    }
    #image {
      width: 24px;
      width: 24px;
    }
    #text {
      font-size: 14px;
    }

    :host(:hover) {
      background: #f0f0f0;
    }

    :host(:hover) #title {
      color: red;
    }

    @media (max-width: 768px) {
      #title {
        font-size: 18px;
      }
    }
  </style>
</macaron-component>
<macaron-component name="my-other-component"> ... </macaron-component>

Top-level structure #

<script type="module" src="..."> tags #

The links to scripts that register external Web Components. Each script tag must contain the type="module" attribute and the src attribute.

<style> tag #

The global CSS definitions. The definitions are contained in the :root pseudo-element.

<macaron-component> tags #

The components. A .macaron file can contain multiple components.

<macaron-component> - Component definition #

Attributes #

• name: the tag name of the component

Children #

<macaron-variant> tags #

The variants of the component. A default variant is always present.

A <template> tag #

The DOM structure of the component.

A <style> tag #

The styles of the component. Supported selector patterns are as follows (other patterns are ignored):

/* styles for the default variant */
:host {
  /* style of the root element */
}
#title {
  /* style of an inner element */
}

/* styles for a variant with a selector */
:host(:hover) {
  /* style of the root element */
}
:host(:hover) #title {
  /* style of an inner element */
}

/* styles for a variant with a media query */
@media (max-width: 768px) {
  :host {
    /* style of the root element */
  }
  #title {
    /* style of an inner element */
  }
}

<macaron-variant> - Component Variant #

Attributes #

• x: The horizontal position of the variant in the editor.
• y: The vertical position of the variant in the editor.
• width: The width of the variant in the editor. (optional)
• height: The height of the variant in the editor. (optional)
• background-color: The background color of the variant in the editor. (optional)
• selector: The selector of the variant. (optional)
  • Example: when the selector is set to :hover, the variant will be applied when the component (:host) is hovered.
• media: The media query of the variant. (optional)
  • When the media is set, the variant will be applied when the media query is satisfied.

A <macaron-variant> without both selector and media becomes the default variant.