We are working very hard to bring you the best documentation possible.

HTML DOCUMENTS

Tokens

Tokens serve as place holders that are replaced by content intended for the HTML document. fusion.ssg recognizes three types of tokens:

  1. simple tokens
  2. template tokens
  3. include tokens

Simple Tokens

syntax: {token-name}

Simple token declarations like the above that fusion.ssg finds in your developing HTML documents are replaced by their respective property values. Simple token property values can be declared in either a template's front matter or in fusion.json, your project's configuration file. If the same token name is used in both, the token's value declared in front matter takes precedence.

Front matter with three simple token property declarations.


---
tokens: {
    docTitle: Cats,
    breed: Persian,
    catName: Felix
}
---

An HTML document with three simple tokens.


<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>{docTitle}-{breed}</title>
    </head>
    <body>
        <main>
            <h1>{catName}</h1>
            {{template}}
        </main>
    </body>
</html>

The resulting HTML document after three simple token values have been applied.


<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Cats-Persian</title>
    </head>
    <body>
        <main>
            <h1>Felix</h1>
            ⋮
        </main>
    </body>
</html>

Unresolved Simple Token Reporting

Introduced in v1.1.0

At the end of each build cycle, fusion.ssg will report any unresolved simple tokens that it finds in your project's generated HTML documents. These warnings indicate that either the token name has been misspelled or that its value has not been declared.

report of unresolved tokens

Auto Generated Simple Tokens

Introduced in v1.2.0

Besides the simple tokens that you define in your template's front matter and globally in your project's fusion.json file, fusion.ssg also defines the following simple tokens, whose values it has obtained from the meta data associated with your posts templates, that you can use:

  • {postDate} - the post date extracted from the post's file name and converted to a locale date string e.g. "mm/dd/yyyy".
  • {categories} - the categories extracted from the post's front matter post.categories property and converted to a path e.g. "cata/catb/catc".
  • {tags} - the tags extracted from the post's front matter post.tags property and converted to a comma separated list e.g. "taga,tagb,tagc".

Template Tokens

syntax: {{template}}

Template tokens are only relevant in pages and are replaced by the content of their associated templates.

template is a reserved symbol and {{template}} should only be used in this context.

An HTML document with a template token.


<body>
    <main>
        {{template}}
    </main>
</body>

The resulting HTML document after a template's content has been applied.


<body>
    <main>
        <p>Cats are amazing!<p>
    </main>
</body>

Include Tokens

syntax: {{path/to/include}} minus file type

Include tokens are relevant in pages and templates and are replaced by their respective include file's content. The path to the respective include file should not contain its file type.

An HTML document with two include tokens.


<body>
    {{header}}
    <main>
        ⋮
    </main>
    {{footer}}
</body>
The include tokens are pointing to two files, src/includes/header.[ md|html ], and src/includes/footer.[md|html].

The resulting HTML document after the content from the two include files have been applied.


<body>
    header content...
    <main>
        ⋮
    </main>
    footer content...
</body>