SHERIFF
SHERIFF
0.18.0 31 Pages
ddonche/sheriff
0.18.0
1
0
docs reference
[[templates]]

Templates

By Sheriff Docs ~ 22 min read

Templates are an important part of Sheriff's theme system. They determine how you want to configure all the pieces Sheriff gives you (tokens), which fit into token slots in layout files. Each portal has its own templates.yall file; this way you can have multiple sites with multiple configurations.

The Big Picture

Each page you make in Sheriff will say in the frontmatter what kind of page it is. This tells Sheriff which layout to use when it builds each page. The default ones that come with Outpost and Siegemate themes are:

  • Blog used for individual blog posts
  • Blog Index used for the page where you display all your blog posts
  • Docs used for individual documentation pages
  • Index used for any "intro" page for a specific section
  • Wiki used for individual wiki pages

Each layout has slots built in. Think of these like "this type of thing goes here." An example might be a header slot, or a page title slot. Some slots are self-explanatory, and you won't be changing them up much in your configuration. Where templates come in: you tell Sheriff what you want to go into each slot.

Sheriff builds your page by taking the selected layout, inserting your page content, and then filling each slot with the tokens defined in your template.

Frontmatter
    │
    ▼
Choose Layout
    │
    ▼
Load Template
    │
    ▼
Inject Tokens
    │
    ▼
Finished HTML

Template File Location

Your templates.yall file resides in themes directory in the root of each portal.

Each portal's themes folder will include an override file and the template file:

site/
└── portals/
    └── sheriff/
        └── themes/
            └── outpost/
                ├── override.css
                └── templates.yall
site/
└── portals/
    └── sheriff/
        └── themes/
            └── outpost/
                ├── override.css
                └── templates.yall

This template file corresponds to the Outpost theme, specifically. If you have any other themes in your project (you may want to switch between them for testing or to try them out), you will need to touch both templates files.

docs.html
     │
     ▼
themes/outpost/templates.yall
     │
     ▼
slot → token mapping

Editing a Template File

Simply open the template file in any text editor. You may not need to change anything at all. Below you will see a default template file for the Outpost theme. Notice a few things:

  • layouts keyword: this is your bottom level called layouts; this will never change
  • each layout: each layout page will be listed at this level; this will only change if you rename a layout page or add new ones
  • slots keyword: this level says slots; this will never change
  • layout slots: here you will see all slots from each layout page listed
  • tokens: this is where you pick what actual token goes into each slot
Note
When we say "edit your templates page", we are talking about rearranging the tokens into different slots. You can experiment here. It may help to save the original copy so you can revert back to default if you need to.
Important
In Sheriff, if a theme expects a token in a slot, you MUST have something there. See below for the section on removing slots.

layouts:
  docs:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      # HEADER NAV: use the 'header' menu as DROPDOWN
      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      # LEFT NAV: use the 'left_docs' menu as SIDEBAR
      LEFT_NAV:
        - "SCOUT::left_docs_SIDEBAR"

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "SCOUT::BREADCRUMBS"
        - "SCOUT::TOC"

      # FOOTERS: use footer_* menus as FLAT
      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"

      HEADERLEFT:
        - "PAGE::META"
      HEADERRIGHT:
        - "TRAILBOSS::CANONLINK"
      PAGEMETALEFT:
        - "BADGE::READTIME"
      PAGEMETARIGHT:
        - "BADGE::UTILICONS"

      SCRIPTS:
        - "BRINDLE::SCRIPTS"

  blog:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      # Same main header nav
      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      LEFT_NAV: []

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "SCOUT::BREADCRUMBS"
        - "CAMPFIRE::BLOG_LIST"

      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"

      HEADERLEFT:
        - "PAGE::META"
      HEADERRIGHT:
        - "TRAILBOSS::CANONLINK"
      PAGEMETALEFT:
        - "BADGE::READTIME"
      PAGEMETARIGHT:
        - "BADGE::UTILICONS"

      SCRIPTS:
        - "BRINDLE::SCRIPTS"

  blog_index:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      LEFT_NAV: []

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "CAMPFIRE::BLOG_LIST"

      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"
layouts:
  docs:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      # HEADER NAV: use the 'header' menu as DROPDOWN
      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      # LEFT NAV: use the 'left_docs' menu as SIDEBAR
      LEFT_NAV:
        - "SCOUT::left_docs_SIDEBAR"

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "SCOUT::BREADCRUMBS"
        - "SCOUT::TOC"

      # FOOTERS: use footer_* menus as FLAT
      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"

      HEADERLEFT:
        - "PAGE::META"
      HEADERRIGHT:
        - "TRAILBOSS::CANONLINK"
      PAGEMETALEFT:
        - "BADGE::READTIME"
      PAGEMETARIGHT:
        - "BADGE::UTILICONS"

      SCRIPTS:
        - "BRINDLE::SCRIPTS"

  blog:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      # Same main header nav
      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      LEFT_NAV: []

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "SCOUT::BREADCRUMBS"
        - "CAMPFIRE::BLOG_LIST"

      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"

      HEADERLEFT:
        - "PAGE::META"
      HEADERRIGHT:
        - "TRAILBOSS::CANONLINK"
      PAGEMETALEFT:
        - "BADGE::READTIME"
      PAGEMETARIGHT:
        - "BADGE::UTILICONS"

      SCRIPTS:
        - "BRINDLE::SCRIPTS"

  blog_index:
    slots:
      STYLELINK:
        - "BRINDLE::STYLE"
      LOGO:
        - "BRINDLE::LOGO"
      BRANDNAME:
        - "BRINDLE::BRANDNAME"
      VERSION:
        - "BADGE::VERSION"
      THEMESWITCHER:
        - "BRINDLE::THEMESWITCHER"
      VERSIONSWITCHER:
        - "BRINDLE::VERSIONSWITCHER"
      SEARCH:
        - "PROSPECTOR::SEARCH_INPUT"
      REPO:
        - "BADGE::REPO"

      HEADER_NAV:
        - "SCOUT::header_DROPDOWN"

      LEFT_NAV: []

      SIDEBAR_TOP:
      SIDEBAR_MAIN:
        - "CAMPFIRE::BLOG_LIST"

      FOOTER_LEFT:
        - "SCOUT::footer_left_FLAT"
      FOOTER_RIGHT:
        - "SCOUT::footer_right_FLAT"

Removing Slots

Sheriff themes define a set of slots, and templates.yall specifies which tokens are rendered into each slot.

If you do not want something displayed on your final page, do not delete the slot from templates.yall. A missing slot is treated as an unresolved layout placeholder.

Instead, replace the token with the built-in Goblin token "GOBLIN::EMPTY".

This explicitly tells Sheriff to render nothing for that slot while preserving the layout contract.

For example, if your wiki or documentation site does not need a version badge:

VERSION:
  - "GOBLIN::EMPTY"
VERSION:
  - "GOBLIN::EMPTY"

The version slot will remain in the layout, but no output will be rendered.

Layouts vs Templates

It's important to note that layouts work hand-in-hand with templates. Layouts live in Sheriff core. These files tell Sheriff the overall layout of each type of page so it can build the html properly.

Templates remain portal-owned. These tell Sheriff where you want to place specific elements *within * the layout.

Why?

  • Layouts define structure
  • Templates define slot wiring

This gives portals control over how content is assembled, while keeping layout HTML centralized and upgrade-safe.

Layout Example

Below you will see an example layouts page so you can see how the slots are configured.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    {{{PAGE::SEO}}}
    {{{SLOT::STYLELINK}}}
    {{{ASSETS::HEAD}}}
</head>
<body>
    <div class="sheriff-shell" id="top">
        <header class="sheriff-header">
          <div class="sheriff-header-top">
            <div class="sheriff-header-left">
              <a href="/" class="sheriff-logo-link">
                {{{SLOT::LOGO}}}
                <div class="sheriff-logo-text-wrap">
                  {{{SLOT::BRANDNAME}}}
                  {{{SLOT::VERSION}}}
                  {{{BADGE::PAGE_COUNT}}}
                </div>
              </a>
            </div>
            <div class="sheriff-header-right">
              {{{SLOT::THEMESWITCHER}}}
              {{{SLOT::REPO}}}
            </div>
          </div>
          <div class="sheriff-header-bottom">
            {{{SLOT::HEADER_NAV}}}
            {{{SLOT::SEARCH}}}
          </div>
        </header>
        <div class="sheriff-main-layout-three">
            {{{SLOT::LEFT_NAV}}}
            <article class="sheriff-article">
              <!-- Page header (meta strip + title + byline) -->
              <header class="sheriff-page-header">
                <!-- Top meta strip -->
                <div class="sheriff-page-meta-bar">
                  <div class="sheriff-page-meta-left">
                    {{{SLOT::HEADERLEFT}}}
                    <!-- e.g. THEME PREVIEW · ARTICLE -->
                  </div>
                  <div class="sheriff-page-meta-right">
                    {{{SLOT::HEADERRIGHT}}}
                    <!-- e.g. canonical wikilink + copy icon -->
                  </div>
                </div>
                <!-- Title (your existing .sheriff-article h1 + ::after underline) -->
                <h1>
                  {{{PAGE::TITLE}}}
                </h1>
                <div class="sheriff-title-underline"></div>
                <!-- Byline / meta row -->
                <div class="sheriff-page-byline">
                  <div class="sheriff-page-byline-main">
                    By
                    <span class="sheriff-page-byline-author">
                      {{{PAGE::AUTHOR}}}
                    </span>
                    {{{SLOT::PAGEMETALEFT}}}
                    <!-- e.g. " · " + BADGE::READTIME -->
                  </div>
                  <div class="sheriff-page-byline-actions">
                    {{{SLOT::PAGEMETARIGHT}}}
                    <!-- e.g. BADGE::UTILICONS -->
                  </div>
                </div>
                <hr class="sheriff-page-header-divider" />
              </header>
              <!-- Markdown / main content -->
              {{{PAGE::CONTENT}}}
              <div class="sheriff-clear"></div>
            </article>
            <aside class="sheriff-toc">
              <div class="sheriff-focus-slot">
                  {{{SITE::FOCUS_PANEL}}}
              </div>
                {{{SLOT::SIDEBAR_TOP}}}
                {{{SLOT::SIDEBAR_MAIN}}}
            </aside>
        </div>
        <footer class="sheriff-footer">
            <div class="sheriff-footer-left">
                {{{SLOT::FOOTER_LEFT}}}
            </div>
            <div class="sheriff-footer-right">
                {{{SLOT::FOOTER_RIGHT}}}
            </div>
        </footer>
    </div>
    <a href="#top" class="sheriff-back-to-top" aria-label="Back to top"></a>
    {{{SLOT::SCRIPTS}}}
    {{{ASSETS::END}}}
</body>
</html>
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    {{{PAGE::SEO}}}
    {{{SLOT::STYLELINK}}}
    {{{ASSETS::HEAD}}}
</head>
<body>
    <div class="sheriff-shell" id="top">
        <header class="sheriff-header">
          <div class="sheriff-header-top">
            <div class="sheriff-header-left">
              <a href="/" class="sheriff-logo-link">
                {{{SLOT::LOGO}}}
                <div class="sheriff-logo-text-wrap">
                  {{{SLOT::BRANDNAME}}}
                  {{{SLOT::VERSION}}}
                  {{{BADGE::PAGE_COUNT}}}
                </div>
              </a>
            </div>
            <div class="sheriff-header-right">
              {{{SLOT::THEMESWITCHER}}}
              {{{SLOT::REPO}}}
            </div>
          </div>
          <div class="sheriff-header-bottom">
            {{{SLOT::HEADER_NAV}}}
            {{{SLOT::SEARCH}}}
          </div>
        </header>
        <div class="sheriff-main-layout-three">
            {{{SLOT::LEFT_NAV}}}
            <article class="sheriff-article">
              <!-- Page header (meta strip + title + byline) -->
              <header class="sheriff-page-header">
                <!-- Top meta strip -->
                <div class="sheriff-page-meta-bar">
                  <div class="sheriff-page-meta-left">
                    {{{SLOT::HEADERLEFT}}}
                    <!-- e.g. THEME PREVIEW · ARTICLE -->
                  </div>
                  <div class="sheriff-page-meta-right">
                    {{{SLOT::HEADERRIGHT}}}
                    <!-- e.g. canonical wikilink + copy icon -->
                  </div>
                </div>
                <!-- Title (your existing .sheriff-article h1 + ::after underline) -->
                <h1>
                  {{{PAGE::TITLE}}}
                </h1>
                <div class="sheriff-title-underline"></div>
                <!-- Byline / meta row -->
                <div class="sheriff-page-byline">
                  <div class="sheriff-page-byline-main">
                    By
                    <span class="sheriff-page-byline-author">
                      {{{PAGE::AUTHOR}}}
                    </span>
                    {{{SLOT::PAGEMETALEFT}}}
                    <!-- e.g. " · " + BADGE::READTIME -->
                  </div>
                  <div class="sheriff-page-byline-actions">
                    {{{SLOT::PAGEMETARIGHT}}}
                    <!-- e.g. BADGE::UTILICONS -->
                  </div>
                </div>
                <hr class="sheriff-page-header-divider" />
              </header>
              <!-- Markdown / main content -->
              {{{PAGE::CONTENT}}}
              <div class="sheriff-clear"></div>
            </article>
            <aside class="sheriff-toc">
              <div class="sheriff-focus-slot">
                  {{{SITE::FOCUS_PANEL}}}
              </div>
                {{{SLOT::SIDEBAR_TOP}}}
                {{{SLOT::SIDEBAR_MAIN}}}
            </aside>
        </div>
        <footer class="sheriff-footer">
            <div class="sheriff-footer-left">
                {{{SLOT::FOOTER_LEFT}}}
            </div>
            <div class="sheriff-footer-right">
                {{{SLOT::FOOTER_RIGHT}}}
            </div>
        </footer>
    </div>
    <a href="#top" class="sheriff-back-to-top" aria-label="Back to top"></a>
    {{{SLOT::SCRIPTS}}}
    {{{ASSETS::END}}}
</body>
</html>

Notice how the layout is mostly html and css. Sheriff will take the layout file and use this to "inject" your page's content, along with other tokens. You can see all the token slots right in the layout. They look like this:

{{{SLOT::HEADER_NAV}}}
{{{PAGE::TITLE}}}
{{{PAGE::CONTENT}}}
{{{SLOT::HEADER_NAV}}}
{{{PAGE::TITLE}}}
{{{PAGE::CONTENT}}}

This simply tells the Stagehand module exactly where to inject your content. All the tokens in your template file will be injected into the proper slot.

Modules Involved

The following modules are involved in your site's build process:

  • Stagehand - responsible for using the correct layout and template for each page