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

Layouts

By Sheriff Docs ~ 16 min read

Layouts are an important part of Sheriff's theme system. They determine how each page type is built. Each theme comes with several layouts out of the box. You can add new layouts to themes.

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:

  • Admin used for generated pages (like All Pages, Wanted Pages, categories) or pages you don't want author info
  • 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

Theme Location (Sheriff Core)

To know exactly which layouts your themes include, look inside the theme's directory.

All themes live inside Sheriff itself:

sheriff-core/
└─ themes/
   └─ outpost/
      ├─ css/
      │  └─ outpost.css
      ├─ layouts/
      │  └─ docs.html
      |  └─ blog.html
      |  └─ blog_index.html
      └─ scout_nav.yall

All your layout files will be in the layouts folder.

Using a Layout

To use any layout, simply indicate the layout in the frontmatter for the page you are making/editing. The example below shows that the admonitions page uses the docs layout style.

^^^^
title: Admonitions & Spoilers
author: Sheriff Docs
layout: docs
meta_kind: tutorial
meta_type: docs
summary: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers.
gloss: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers.
^^^^
^^^^
title: Admonitions & Spoilers
author: Sheriff Docs
layout: docs
meta_kind: tutorial
meta_type: docs
summary: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers.
gloss: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers.
^^^^

The location:

layout: docs
      │
      ▼
themes/outpost/layouts/docs.html

Making a Custom Layout

The easiest way to make a custom layout is to duplicate an existing one. In fact, it's better to make a new layout than to edit existing ones (unless you are duplicating a theme to make a new one). This way, if you ever upgrade your Sheriff core install, your files won't be overwritten.

Tip
This is the same method used to make Wordpress child themes and such.

Once you make a custom layout, add a corresponding entry to the templates.yall file for every theme that should use it.

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.

Example

<!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. How does it know what you want in each slot? It reads your portal's templates.yall file. We'll cover templates in the next section.

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