Tokens

Tokens are a built-in feature of Goblin. Think of them like variables whose value is generated by another part of the system. That value can be anything: text, HTML, CSS, JavaScript, JSON, or any other type of data.

Sheriff uses tokens as its primary content injection system. If you've used WordPress before, you can think of them as being similar to shortcodes, except tokens are assembled automatically during the build process rather than being written directly into your page content.

Most tokens are intended to be used by themes through layouts and templates. However, some modules expose tokens that are designed to be placed directly inside your Markdown content.

The Big Picture

When Sheriff builds a page, the process looks something like this:

Markdown Page
      │
      ▼
Choose Layout
      │
      ▼
Read templates.yall
      │
      ▼
Resolve Tokens
      │
      ▼
Generate Final HTML

Markdown Page
      │
      ▼
Choose Layout
      │
      ▼
Read templates.yall
      │
      ▼
Resolve Tokens
      │
      ▼
Generate Final HTML

The layout defines where content should go.

The template defines which tokens should fill each slot.

The modules generate the actual content for those tokens.

What Is a Token?

A token has a namespace followed by a name.

MODULE::TOKEN

MODULE::TOKEN

Examples:

PAGE::TITLE
BRINDLE::STYLE
BRINDLE::LOGO
SCOUT::HEADER_DROPDOWN
PROSPECTOR::SEARCH_INPUT
BADGE::REPO
SHERIFF::PATTERN_NAME
GOBLIN::EMPTY

PAGE::TITLE
BRINDLE::STYLE
BRINDLE::LOGO
SCOUT::HEADER_DROPDOWN
PROSPECTOR::SEARCH_INPUT
BADGE::REPO
SHERIFF::PATTERN_NAME
GOBLIN::EMPTY

Each token represents a value that another part of Sheriff knows how to generate.

Where Do Tokens Come From?

Every Sheriff module can expose tokens.

Some modules simply perform work during the build process and never expose any tokens.

Other modules generate reusable pieces of content that themes can place wherever they want.

For example:

Brindle
    └── Theme assets
        • STYLE
        • LOGO
        • BRANDNAME

Scout
    └── Navigation
        • HEADER_DROPDOWN
        • LEFT_DOCS_SIDEBAR
        • FOOTER_LEFT_FLAT

Prospector
    └── Search
        • SEARCH_INPUT

Badge
    └── Metadata badges
        • VERSION
        • REPO
        • READTIME
        • UTILICONS

Brindle
    └── Theme assets
        • STYLE
        • LOGO
        • BRANDNAME

Scout
    └── Navigation
        • HEADER_DROPDOWN
        • LEFT_DOCS_SIDEBAR
        • FOOTER_LEFT_FLAT

Prospector
    └── Search
        • SEARCH_INPUT

Badge
    └── Metadata badges
        • VERSION
        • REPO
        • READTIME
        • UTILICONS

Every module is responsible for generating its own output.

Tokens Inside Templates

Templates decide which token should be injected into each layout slot.

For example:

HEADER_NAV:
  - "SCOUT::header_DROPDOWN"

SEARCH:
  - "PROSPECTOR::SEARCH_INPUT"

LOGO:
  - "BRINDLE::LOGO"

HEADER_NAV:
  - "SCOUT::header_DROPDOWN"

SEARCH:
  - "PROSPECTOR::SEARCH_INPUT"

LOGO:
  - "BRINDLE::LOGO"

This tells Sheriff exactly which module should provide the content for each slot.

Tokens Inside Layouts

Layouts never reference modules directly.

Instead, they contain slots.

{{{SLOT::HEADER_NAV}}}

{{{SLOT::SEARCH}}}

{{{SLOT::LOGO}}}

{{{SLOT::HEADER_NAV}}}

{{{SLOT::SEARCH}}}

{{{SLOT::LOGO}}}

When Sheriff builds the page:

1. It reads the layout.
2. It finds the slot.
3. It looks in templates.yall to see which token belongs there.
4. It asks the responsible module to generate that token.
5. It injects the generated content into the layout.

The finished page contains the generated HTML—not the token itself.

Tokens Can Generate Anything

Although Sheriff primarily uses tokens to generate HTML, they are not limited to HTML.

A token may generate:

• Plain text
• HTML
• CSS
• JavaScript
• JSON
• SVG
• URLs
• Metadata
• Any other value supported by Goblin

Sheriff simply happens to use them to assemble web pages.

Sheriff-specific Tokens

While modules provide most of the tokens used in Sheriff, the site itself provides the following tokens:

• {{{SHERIFF::PATTERN_NAME}}}: injects a premade pattern into content

Why Tokens?

Tokens keep responsibilities separated.

• Layouts define page structure.
• Templates decide which pieces belong in each slot.
• Modules generate those pieces.
• Stagehand assembles everything into the finished page.

This allows themes and modules to evolve independently while keeping page assembly simple and predictable.

Using Tokens Inside Content

Not all tokens are meant to be used in page layouts and templates. Some of them can be used right inside your content. You just place them where you want them and Sheriff will add it to your page accordingly.

Great examples of this are patterns and the Goblin REPL. Because Sheriff is built in the Goblin programming language (and to host its documentation), it comes with an embeddable Goblin REPL right out of the box.

For example, to use this you simply put this in your content where you want it:

Try it in the REPL:
{{{GOBLIN_REPL::EMBED}}}

Try it in the REPL:
{{{GOBLIN_REPL::EMBED}}}

The code above produces the following output:

Try it in the REPL:

As you can see, it's injected right into your page's content. Try typing :say("Welcome to the Horde!") and pressing run!

The Goblin REPL is just one example. Any module can expose embeddable tokens. This makes it easy to create reusable widgets, interactive components, badges, media viewers, or any other generated content that can be dropped directly into a page. For example, there are currently 31 Pages in total in these docs. All we did was throw the page count badge in our page.

{{{BADGE::PAGE_COUNT}}}

{{{BADGE::PAGE_COUNT}}}

Modules Involved

The following modules participate in Sheriff's token system:

• Stagehand — injects generated token content into layout slots.
• Any module exposing tokens — generates the content requested by Stagehand.