docs reference

[[tokens]]

Tokens

By Goblin Docs ~ 9 min read

Tokens are runtime placeholders that allow Goblin applications, modules, and templates to inject dynamic content into text.

A token is written using triple braces:

{{{MODULE::IDENTIFIER}}}

{{{MODULE::IDENTIFIER}}}

At runtime, Goblin resolves the token and replaces it with the associated value.

Tokens are used throughout the Goblin ecosystem for static site generation, templates, documentation, email generation, and any other system that needs reusable text placeholders.

Token Syntax

Every token follows the same format:

{{{MODULE::IDENTIFIER}}}

{{{MODULE::IDENTIFIER}}}

Examples:

{{{BADGE::VERSION}}}
{{{SITE::TITLE}}}
{{{PAGE::META}}}
{{{BRINDLE::LOGO}}}

{{{BADGE::VERSION}}}
{{{SITE::TITLE}}}
{{{PAGE::META}}}
{{{BRINDLE::LOGO}}}

The parser validates the token shape, while the interpreter or VM resolves the token value at runtime.

Registering Tokens

Tokens may be registered directly by any Goblin code.

:register_token(module, identifier, value)

:register_token(module, identifier, value)

Example:

:register_token("SITE", "TITLE", "Everwind")

:register_token("SITE", "TITLE", "Everwind")

The token may then be used anywhere:

Welcome to {{{SITE::TITLE}}}

Welcome to {{{SITE::TITLE}}}

Output:

Welcome to Everwind

Welcome to Everwind

Resolving Tokens

Goblin provides two forms of token resolution.

Resolve a specific token:

:resolve_token("SITE", "TITLE")

:resolve_token("SITE", "TITLE")

Resolve every token inside a string:

:resolve_token("Welcome to [ERR: MALFORMED TOKEN -> SITE::TITLE]!")

:resolve_token("Welcome to [ERR: MALFORMED TOKEN -> SITE::TITLE]!")

Output:

Welcome to Everwind!

Welcome to Everwind!

Resolution Order

When Goblin encounters a token, it resolves it using the following order:

Registered token store
MODULE::resolve_token(identifier) action (if implemented)
Unresolved token

For example:

{{{BADGE::VERSION}}}

{{{BADGE::VERSION}}}

Goblin first checks whether BADGE::VERSION has been registered.

If not, Goblin attempts to call:

BADGE::resolve_token("VERSION")

BADGE::resolve_token("VERSION")

This allows modules to generate token values dynamically instead of registering every token in advance.

Override Tokens

Goblin includes a built-in override token system.

The following syntax:

override::body | "Hello"

override::body | "Hello"

automatically registers the token:

{{{OVERRIDE::BODY}}}

{{{OVERRIDE::BODY}}}

This allows templates to override portions of generated content without modifying the original template.

Built-in Goblin Tokens

Goblin reserves the GOBLIN namespace for language-defined tokens.

GOBLIN::EMPTY

{{{GOBLIN::EMPTY}}}

{{{GOBLIN::EMPTY}}}

Produces no output.

This token is useful when a layout or template expects content, but the author intentionally wants the location to remain blank.

Example:

VERSION:
  - "GOBLIN::EMPTY"

VERSION:
  - "GOBLIN::EMPTY"

Output:

One common use is disabling optional Sheriff layout slots without modifying the layout itself.

Listing Tokens

Registered tokens can be inspected at runtime.

List every registered namespace:

:list_tokens()

:list_tokens()

List every token within a namespace:

:list_tokens("BADGE")

:list_tokens("BADGE")

These functions only display registered tokens.

Language-defined tokens such as:

GOBLIN::EMPTY

GOBLIN::EMPTY

are intrinsic to Goblin and are not stored in the runtime token registry.

Clearing Tokens

Goblin also provides functions for removing registered tokens.

Clear a single token:

:clear_token("SITE", "TITLE")

:clear_token("SITE", "TITLE")

Clear an entire namespace:

:clear_tokens("SITE")

:clear_tokens("SITE")

Clear every registered token:

:clear_all_tokens()

:clear_all_tokens()

These functions affect only the runtime token registry.

Common Uses

Tokens are commonly used for:

Documentation generators
Static site generation
HTML templates
Email templates
Layout systems
Reusable page components
Branding
Version information
Build metadata
Dynamic content injection

Because tokens are resolved at runtime, the same template can be reused across many projects simply by changing the registered token values.

Philosophy

Tokens are a language-level text substitution system.

Goblin provides the token engine, while applications and modules determine what tokens exist and what values they produce.

This separation keeps Goblin generic while allowing higher-level systems such as Sheriff, Graveyard, and future Goblin applications to build rich template systems without creating compile-time dependencies between components.