Adding to the User Guide

This page explains how to add new entries to the User Guide section of Siter Documentation.

Quick Start

1. Create a new .md file under docs/user/ (or an appropriate subfolder)
2. Add frontmatter at the top of the file
3. Write your content in Markdown
4. Preview locally with npm start
5. Commit and push — the site rebuilds automatically

File Structure

User Guide pages live under docs/user/. The folder structure maps directly to sidebar categories:

docs/user/
├── getting-started.md              → top-level page
├── faq.md                          → top-level page
├── contributing-to-docs.md         → this page
├── features/
│   └── overview.md                 → appears under "Features"
├── account/
│   └── profile.md                  → appears under "Account & Settings"
└── environment-management/
    ├── deployment.md               → appears under "Environment Management"
    └── sso-client-setup.md

To add a page to an existing category, place the file in the matching folder. To create a new category, create a new folder and add pages inside it — then register the category in sidebars-user.ts (see Sidebar Configuration below).

Frontmatter

Every page needs a frontmatter block at the top. At minimum, include sidebar_position to control ordering:

---
sidebar_position: 2
title: My Page Title
---

# My Page Title

Your content here.

Field	Required	Description
sidebar_position	Yes	Numeric order within the sidebar category (lower = higher).
title	No	Overrides the sidebar label. Defaults to the first # heading.
description	No	Used in meta tags and search results.
slug	No	Custom URL path segment (defaults to the filename).

Sidebar Configuration

The sidebar is defined in sidebars-user.ts. Most categories use autogenerated, which means any .md file you drop into the folder is picked up automatically — no config change needed.

If you add a new folder/category, add an entry to sidebars-user.ts:

{
  type: 'category',
  label: 'My New Category',
  items: [{type: 'autogenerated', dirName: 'my-new-category'}],
},

Writing Content

Markdown Features

Docusaurus supports standard Markdown plus some extras:

Admonitions — callout boxes for tips, warnings, etc.:

:::tip
This is a helpful tip.
:::

:::warning
Be careful with this setting.
:::

:::danger
This action cannot be undone.
:::

Tabs — for showing alternatives (e.g., different OS instructions):

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="linux" label="Linux" default>
    Run `./install.sh`
  </TabItem>
  <TabItem value="windows" label="Windows">
    Run `install.bat`
  </TabItem>
</Tabs>

Code blocks — with syntax highlighting and optional title:

```yaml title="docker-compose.yaml"
services:
  siter-api:
    image: siterapi:latest
```

Links to other pages — use relative paths:

See the [deployment guide](./environment-management/deployment.md) for details.

Images — place images in an img/ folder next to your markdown file:

docs/user/features/
├── overview.md
└── img/
    ├── dashboard.png
    └── map-view.png

Then reference them with a relative path:

![Dashboard screenshot](./img/dashboard.png)

Tips for images:

• Use descriptive alt text (the text inside []) for accessibility
• Prefer PNG for screenshots and SVG for diagrams
• Keep file sizes reasonable — resize large screenshots before adding them
• For images shared across multiple pages, place them in static/img/ and use an absolute path: ![Logo](/img/siter-logo.svg)

Style Guidelines

• Use sentence case for headings ("Getting started" not "Getting Started") — except for proper nouns
• Keep pages focused on a single topic
• Lead with the most common use case, then cover edge cases
• Include screenshots when describing UI workflows
• Use tables for reference material (environment variables, config options, etc.)

Previewing Locally

npm start

This starts a dev server at http://localhost:3000 with hot reload. Changes to Markdown files appear instantly.

Building for Production

npm run build

This generates the full static site in the build/ directory and will report any broken links.