File Conventions

This document outlines the file structure, naming and format conventions for all documents in src/content/docs.

Structure

All documents must be created in one of the subfolders of src/content/docs - kb, loa, misc or sop.

For these ‘main’ folders, you cannot modify their name/display name, remove them, or create more. If you feel changes to the main folders are required, contact tech support.

Files and Subfolders

You may freely modify the contents within any of the main folders. This includes modifying, creating and deleting files and subfolders within them.

Folders, their subfolders and files inside the main folders directly correspond to groups, subgroups and documents in the site’s navigation sidebar, respectively. In other words, the sidebar is generated automatically and requires no direct modification. New files & folders should appear as soon as you create them.

Naming

Both files and folders should be named in lowercase-hyphen-separated format. The raw file/foldername is used in the page URL. Therefore, try to keep it short - ideally, less than 3 words. The display name of the page that shows up in the sidebar & page title can be modified in the frontmatter (discussed later) and can be longer.

You also shouldn’t try to name the files or folders specifically to influence the sorting order, as this can also be set using frontmatter.

File and Folder Format

File Frontmatter

Every file must have frontmatter at the very top that contains, at a minimum, the title (display name) which displays at the top of the file and in the sidebar list. You should also add a description which isn’t used directly on the website, but shows up under the website when a link to the page is sent (like on Discord):

---
title: Some Longer Title
description: Information on writing
---

By default, files in a folder are sorted alphabetically on the site. If you want to change that, provide the sidebar → order option. Lower numbers are shown first, and the numbers in different files don’t need to be sequential.

---
title: Some Longer Title
description: Information on writing
sidebar:
  order: 1
---

Despite being in a Markdown file, the frontmatter (between the triple hyphen) is written in YAML format - note that indents matter. If you forget to indent order, it will not work.

The full list of options available to set in file frontmatter are available on the Starlight website.

Warning

Add frontmatter immediately when you create a new file. Missing or improperly formatted frontmatter will immediately crash the site.

Folder frontmatter

Folders need frontmatter as well, but you obviously can’t directly type in a folder. Therefore, each subfolder of the main folder should have a file named _meta.yaml inside that contains folder frontmatter. If you create a folder, create the file immediately so you don’t forget to later.

The format of _meta.yaml is similar but distinct from file frontmatter:

label: Some Group Title
order: 2

If you don’t need to change the sort order, omit the option.

The full list of options available to set in folder frontmatter are available on the Starlight Auto Sidebar website.

Reminder

The main folders do not have a frontmatter file - their properties are set elsewhere.

Browse around the source code of this folder (contributors) for example usages of everything that you’ve read about through this series of documents. Happy writing!