Using Layouts

Layouts are the base templates used in Coal to reduce copy and pasting of elements like navigation or footers

Folder Structure

Coal is opinionated about your folder structure

Your HTML project should look like this

        assets/
            [optional additional CSS/JS/image assets here]
        pages/
            pages-here.html
        layouts-here.html

See examples for a bunch of common solutions, including this documentation website.

Layouts Overview

A layout file is required at the root of your project, this is used to create the basic HTML template to place your page content.

The name of the layout file becomes the name of the tag that you'd use within your page template files, ie layout.html is used as <layout>.

There are a number of special Mustache-inspired tags that can be used in this file:

{{version}} - the location of the version string, generated at build time via an argument (defaults to ISO-8061 string)
{{content}} - the resolved content including any nested components
{{title}} - A <title> tag collected from a page template (defaults to the page file's name uppercased, ie about.html becomes "About")
{{meta}} - any <meta> tags collected from a page template
{{style}} - any <style>; tags collected from a page template
{{script}} - any <script> tags collected from a page template
{{page}} - a lowercase string to denote current page, useful for adding to the body class to mark active states on navigation (see examples/mvp/layout.html)

Sample Layout

Here is a sample layout file, placed inside src/layout.html:

        <!DOCTYPE html>
        <html lang=en>
        <head>
            <meta charset=utf-8>
            <meta name=viewport content="width=device-width,initial-scale=1,maximum-scale=1">
            <meta name=version content="{{version}}">
            {{meta}}
            <title>{{title}}</title>
            {{style}}
        </head>
        <body class="page-{{page}}">
            <header>
                Hi
            </header>
            <main>
                {{content}}
            </main>
            {{script}}
        </body>
        </html>

Using a Layout in a Page

Assuming a layout file exists at src/layout.html, you can use the tag <layout> to designate usage of that particular layout. Also see the examples/mvp/pages/portfolio.html file for an example of using an alternate layout.

        <layout>
            <h1>Welcome to the About Page</h1>
        </layout>

For more detailed information about Pages, see Pages documentation.