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. baseURL tokens
  3. template tokens
  4. 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".

baseURL Tokens

syntax: {baseURL}

If your site is served from a subfolder, such as are sites that are hosted on github.io that do not include a CNAME file, prepend {baseURL} to your site's root relative URLs and during release builds {baseURL} will be replaced by its value, which you define in your project's configuration file, and during development builds will be removed.

{baseURL} is a reserved token and should only be used in this context.

Assign the name of the sub folder that is used to host your site to the baseURL property in your project's fusion.json configuration file, which is located in your project's root folder.

{"baseURL": "/fusion.ssg.docs"}

Prepend the baseURL token to your site's root relative URLs.

<a href="{baseURL}/docs">Docs</a>

When building for release, {baseURL} will be replaced by its value.

<a href="/fusion.ssg.docs/docs">Docs</a>

When building for development, {baseURL} will be removed.

<a href="/docs">Docs</a>

CSS File Support For baseURL Tokens

Introduced in v1.3.0

Beginning with v1.3.0, the use of baseURL tokens is now supported in your project's CSS files and can be applied to any CSS attribute that takes a URL, such as background images for example.

So, for example, if you are building a site that has background images you no longer have to declare 2 URLs for the image, one for development builds, and one for release builds.

Instead, you can just prepend the root relative URL with the baseURL token and the URL will resolve properly for both development and release builds.

Using {baseURL} in CSS.

.hero {
    background-image: url({baseURL}/media/stretching-cat.png);
}

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 token and 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>