Your First Page

By Sheriff Docs ~ 9 min read

Now that you have Sheriff installed and you have started a new portal (site), it's time to write your first piece of content. Sheriff is a static site generator, which means that it generates html content during the build so that your visitors see the final product. This is faster than using dynamic content, such as storing your content in a database.

Note

Dynamic websites work like this: someone visits your page on the internet and your code for that page makes a request for the information it needs, which is stored in the database (this is called a database query). The database fetches the info, returns it to your code, which the web browser then renders into the html the user sees after it's rendered. With static sites, the html is already made, so it just gets served directly. There are benefits to each system.

Since Sheriff generates the end result, the goal is to take simple input and run it through a number of changes to get the final, amazing result (this is called the pipeline in Sheriff):

your markdown content is changed into html
wikilinks are changed into html
special syntax gets changed into html
menus are composed into html
- table of contents is auto generated
- breadcrumbs auto generated
category other pages are auto generated

You get the idea. But in order to do any of that, you must create your pages in the right place. That's what this guide is all about.

Your Content Directory

When it comes to content, you must concern yourself with two directories:

sheriff/site/portals/{portal_name}/content
sheriff/dist/{portal_name}

The first one, your content directory, is where you will store all of your pages, which will be written in markdown (a markup language). The second one, your dist directory, is the finished site after you build it.

Inside your content directory you can have any number of subdirectories. This includes a blog directory (use this only if you want to have a blog provided by Sheriff). Any directories you make inside content will be the same on the other side.

Tip

We highly recommend organizing your content in directories that match your categories. For example, say I have a category called "animals" and in that category I have others like "reptiles", "mammals", etc. You might put those pages inside directories that match, which makes it easier to find them:

{portal_name}/content/animals/reptiles/your_page.md
{portal_name}/content/animals/mammals/your_page.md

{portal_name}/content/animals/reptiles/your_page.md
{portal_name}/content/animals/mammals/your_page.md

You don't have to do it this way, of course, but imagine if you have hundreds of pages.

Making a New Page

There are two ways to write content:

using Sheriff Desk, which includes a built-in text editor
using a text editor of your own

If you use a text editor of your own, such as VS Code, Sublime, Notepad++, simply write your markdown page, to include frontmatter, and save it as a .md file in your content directory where you want it to be.

But until you get the hang of writing frontmatter, we recommend using Sheriff Desk. You will have already seen this admin panel just after installing Sheriff. If you can't remember how to get to it:

/// from your command line, cd into sheriff/dist, then type: 
goblin start

/// from your command line, cd into sheriff/dist, then type: 
goblin start

Then visit http://localhost:5173/ in your web browser. In the left side panel, simply click on Content. You'll be able to pick which portal you want to work with (if you have more than one). From here, at the bottom of the file tree you will see two buttons. New Folder and New Page. Simply click new page, fill out the form, and see your document template get generated.

^^^^
title: Test
author: Janden
layout: wiki
meta_kind: docs
meta_type: entry
summary: 
gloss: 
categories: []
aliases: []
^^^^

# Test

Write your page here.

^^^^
title: Test
author: Janden
layout: wiki
meta_kind: docs
meta_type: entry
summary: 
gloss: 
categories: []
aliases: []
^^^^

# Test

Write your page here.

Let's look at the frontmatter; if you get some things wrong, your site will not build (this why we gave you a Desk admin panel).

title: this is the title that will be displayed on your page
author: this will be displayed on your page, depending on the layout
layout: you must use a layout that exists in your theme; the new page popup in Sheriff Desk reads these exactly, so you cannot get it wrong
meta_kind: what kind of page is this (put whatever you want)
meta_type: what type of page is this (put whatever you want)
summary: provide a sentence that explains what this page is about (optional)
gloss: provide a sentence that defines what this is when you hover a link to this page (optional)
categories: provide any categories (optional)
aliases: provide any other names for this page (links using those names will redirect here)

That's it for the frontmatter. The next part is writing your document.

Using Markdown

Since you must write this in markdown, Sheriff Desk comes with a handy markdown cheat sheet to help you style your page how you like. Just click the ? icon a the top of the editor to see the pop up.

Special Features

You may want to use things like images, links, warnings, spoilers, and specific navigation buttons. We won't give the details here but you can find instructions on these throughout the docs (look in the left sidebar if you get lost). Some things you might want:

One you are done, if you click save in Sheriff Desk, it will automatically build the single page for you. If you would like to see your page in action, go ahead and build portal from Desk and then launch it. Then you can navigate to that page by using .html instead of .md:

/// if your content page was
content/docs/getting_started/first_page.md

/// go to
content/docs/getting_started/first_page.html

/// if your content page was
content/docs/getting_started/first_page.md

/// go to
content/docs/getting_started/first_page.html

You will see your page. You can make further changes in Desk and save, then refresh the page to see your changes.