docs guide

[[building-sites]]

Building Sites

By Sheriff Docs ~ 8 min read

Sheriff's main objective is to help you build your documentation or wiki site as easily as possible. We offer you two ways to do this:

command line interface (CLI)
Sheriff Desk (the admin panel that comes with Sheriff)

Sites

The first thing we should cover is that you can build as many sites as you want with Sheriff, and Sheriff Desk will track them all. In Sheriff, we call a site a portal. For example, perhaps you want a separate site for an open source project, a personal fiction wiki, and a wiki about trains. In Sheriff, you can build them all.

Building Portals/Sites

Sheriff can build content at three different levels depending on what you need:

The entire collection (all portals)
A single portal
A single page within a portal

All three use the same rendering engine. The difference is simply how much of the site Sheriff compiles.

Choosing the right build mode can dramatically speed up development and debugging.

The three build modes

Build Target	What Sheriff Compiles	When to Use It
All Portals	Every portal and page	Production builds
Portal	One portal and all its pages	Developing a specific documentation area
Single Page	One document only	Writing or debugging a specific page

Building All Portals

You can build all your portals at once. This compiles every portal and page in your Sheriff project.

Use this for final builds or when you want to confirm the whole collection works.

CLI Example: In your CLI, you must cd into your sheriff/sheriff-core directory. Once there, run:

goblin run main.gbln all

During a full build Sheriff will:

Discover every portal
Load each portal's nav.yall
Run sweep passes
Render Markdown
Apply layouts
Generate navigation (TOC, breadcrumbs, menus)
Write all output files

Full builds take the longest but ensure the entire collection is correct.

Building a Single Portal

A portal build compiles only one portal and its pages.

This is useful when you are working on a specific documentation section.

CLI Example: In your CLI, you must cd into your sheriff/sheriff-core directory. Once there, run:

goblin run main.gbln {portal_name} <---- put your portal name here

Sheriff will:

Load the selected portal
Build all pages inside that portal
Run portal navigation generation
Apply layouts
Write the output for that portal only

Portal builds are much faster than full builds and are ideal when developing a specific documentation area.

Building a Single Page

A single-page build compiles only one document.

CLI Example: In your CLI, you must cd into your sheriff/sheriff-core directory. Once there, run:

goblin run main.gbln {portal_name} page {relative path}

/// example
goblin run main.gbln goblin page docs/loops.md <---- the loops page in the docs directory of the goblin portal

Sheriff will:

Parse the page frontmatter
Render Markdown
Run page sweeps
Apply the layout
Output the resulting HTML

Single page builds are extremely fast and are perfect for:

Writing documentation
Testing Markdown
Debugging layouts
Verifying sweep behavior

You do not need to rebuild the entire portal just to preview one document.

Important

If you change something that touches more than just the one document, such as your nav.yall or a category, build the whole portal.

Why Single Page Builds Matter

Single-page builds provide a tight development loop.

Instead of rebuilding the entire site every time you edit a file, you can compile only the page you're working on.

This allows you to:

Iterate quickly
Test formatting changes
Debug rendering issues
Validate frontmatter

It turns Sheriff into a fast documentation authoring tool, not just a static site generator.

How Sheriff Decides What to Build

Sheriff looks at the argument you pass to the build command.

Input	Result
all	Build all portals
Portal path	Build that portal
Page path	Build only that page

This means the same command can handle all build levels.

Typical Workflow

Most authors use a simple workflow:

Write a page
Build the page
Adjust formatting
Repeat

Example:

goblin run main.gbln {portal_name} page docs/loops.md

When the page looks correct, run a portal or full build to verify the rest of the site.

Troubleshooting

My page builds but the portal doesn't

Portal builds also generate navigation and other portal-level systems.

A page can render correctly while the portal build fails due to:

navigation issues
missing layouts, templates, themes, etc
portal configuration errors

My portal builds but the full suite fails

Full builds include all portals, so if there are any portal-specific errors, they will come up in a full build.

Summary

Sheriff supports three build scopes:

Full build — everything
Portal build — one documentation area
Page build — a single document

Using the correct build scope makes Sheriff faster and easier to work with during development.