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 following the style guide
4. For feature pages, use the feature entry template
5. Update the Capabilities overview to include a link to your new page
6. Preview locally with npm start
7. 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
├── 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
└── contributing/
    ├── adding-to-the-user-guide.md → this page
    ├── feature-entry-template.md   → template for new feature pages
    └── style-guide.md              → writing and formatting standards

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

Follow these guidelines for consistent, high-quality documentation:

• Sentence case for headings — capitalize only the first word and proper nouns
• Bold for UI elements: click Save, select Analysis
• Imperative mood for instructions: "Click," not "You should click"
• Active voice: "Siter saves your changes," not "Your changes are saved"
• Numbered lists for steps, bullet lists for non-sequential items
• Screenshots only when the UI isn't self-explanatory — include alt text
• Admonitions sparingly — max 2 per section, don't stack them
• No jargon — write for non-technical end users
• Consistent terms — use "click," "select," "enter," "sign in," "navigate to"

For comprehensive guidance including terminology standards, formatting rules, and a pre-submission checklist, see the full Style Guide.

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.