Welcome to the new Kalastatic!

What is Kalastatic?

Kalastatic is a super-simple static site generator, powered by the magic of Twig. It allows front-end developers who are familiar with Twig to quickly and conveniently create static sites, prototypes, and complicated applications like styleguides without the need of a CMS backend.

Why use Twig?

Twig is a very powerful templating system that was created for applications powered by PHP as part of the Symphony framework. Using just a slim collection of tags, filters, and functions, Twig provides an outsized ability to manipulate and display content in ways that previously would have required extensive and complicated custom code in PHP or other languages.

Since Twig is the templating system used by modern versions of Drupal, it has broad adoption in the web development community, and any front-end Drupal developers should already know everything they need to start using Kalastatic.

Kalastatic uses Twig.js which is a pure JavaScript implementation of the Twig templating language, allowing Twig to be integrated into the node-based workflow that is used by most front-end developers for tasks like CSS compilation and library inclusion.

Why no Markdown or YML files?

Most static site generators store content in a separate format from the templates that are used to display it, usually either in Markdown files, or other structured data files such as YML for JSON. This is under the assumption that those formats are simpler and easier to understand by editors than the html and other markup syntax that is used by the underlying templates.

In practice, these alternate formats are not much simpler than the underlying markup they are trying to obscure. For example, **bold text** in Markdown is not necessary simpler to remember than <strong>bold text</strong>, and having multiple formats also means that developers need to memorize multiple formats and perhaps create complicated functions to convert between the two.

File formats like YML and JSON are not particually well suited to storing complicated markup and long blocks of text in a way that are easy to view and edit by humans. They have been optimized for machine generation and consumption, and even minor syntax mistakes may lead to complete failure of the site generation.

What does content creation in twig look like?

By creating page templates and then extending them, you quickly and easily wrap your page content in a large amount of markup that is shared across the pages on your site:

{# Wrap the content for this page in the common page template. #}
{% extends "@templates/page.html.twig" %}

{# Set the page title, which is output in the title and h1 elements. #}
{% set title = "Welcome to the new Kalastatic!" %}

{# This block contains your page content. #}
{% block content %}
  [Page content will go here...]
{% endblock content %}

Example index.html.twig file using the page template defined for this site, which provides a variable to hold the page title and a block to hold the page content.

By defining component templates and embedding them into your page, other chunks of markup can be standardized across many smaller repeating parts of your website.

{# This block contains your page content. #}
{% block content %}

  {% embed "@components/sections/section--text.html.twig" with { 'heading': "What is Kalastatic?" } %}
    {% block text %}
      <p>
        Kalastatic is a super-simple static site generator, powered by the magic
        of Twig. It allows front-end developers who are familiar with Twig to
        quickly and conveniently create static sites, prototypes, and complicated
        applications like styleguides without the need of a CMS backend.
      </p>
    {% endblock text %}
  {% endembed %}

{% endblock content %}

Example of placing a text section component that was defined for this site within the content block from the page template above. The section heading is passed in with a variable, and the content is placed in a block named 'text'. The text block can contain paragraph tags and any other HTML markup that is needed.

While creating pages this way requires a bit more technical knowledge than just plugging text into CMS edit forms, it should not be a challenge for front-end developers with Twig and HTML knowledge, and even non-technical editors should be able to see how things work when given an example to use as a reference.