docusaurus-conventions

name: docusaurus-conventions description: Formatting rules, page structure templates, and Docusaurus-specific conventions for the Lichtblick documentation site.

Docusaurus Conventions

Applies to all documentation pages in docs/ and guides/.

Frontmatter

Every page must include all required frontmatter fields listed below.

Required Fields

Field	Description
`title`	Page title shown in the sidebar and browser tab
`description`	One sentence summarizing the page — used for SEO and Algolia search
`sidebar_position`	Integer controlling the page order within its sidebar section
`keywords`	List of search keywords for Algolia (e.g., `[gauge, panel, visualization]`)

Optional Fields

Field	When to Use
`id`	When the filename differs from the desired URL slug (e.g., `id: 3d` for `3d-panel.md`)
`slug`	For section root pages that need a custom URL path

Example

---
id: gauge
title: Gauge Panel
description: Display a single numeric value as a gauge with configurable ranges and colors.
sidebar_position: 5
keywords: [gauge, panel, numeric, visualization, threshold]
---

Page Structure — Panel Documentation

Use this template for documenting Lichtblick panels:

---
title: Panel Name
description: One-sentence summary.
sidebar_position: 1
keywords: [panel, keyword1, keyword2]
---

## Overview

One to three paragraphs explaining what the panel does and when to use it.

![panel-name](images/panel-name.png)

## Settings

### Setting Category

| Field | Description |
| --- | --- |
| **Field Name** | What it does. Active voice, present tense. |

## Supported Messages

List the message schemas this panel subscribes to, with links to
the message-schemas section.

## User Interactions

Describe mouse, keyboard, and context-menu interactions.

## Troubleshooting

Common issues and solutions (include only if applicable).

Page Structure — Guide / Tutorial

Use this template for step-by-step guides:

---
title: Guide Title
description: One-sentence summary.
sidebar_position: 1
keywords: [guide, keyword1, keyword2]
---

## Introduction

What the reader will accomplish and prerequisites.

## Steps

### 1. First Step

Instructions with screenshots.

### 2. Second Step

More instructions.

## Summary

What was accomplished and links to related documentation.

Markdown Formatting

Headings

ATX-style only (#, ##, ###)
One blank line before and after each heading
Do not skip heading levels (e.g., go from ## to ####)

UI Elements

Bold for UI element names: Add panel, Settings, Display frame
Do not use quotes or backticks for UI elements

Code and Config Values

Backticks for code, config values, topic names, field names: receiveTime, /camera/image_raw, frame_id
Backticks for file paths: docs/visualization/panels/

Tables

Use tables for settings, parameters, and option lists. Always bold the field name column:

| Field | Description |
| --- | --- |
| **Field Name** | Description in active voice. |

Images

Format: PNG only
Filenames: lowercase, hyphenated (e.g., gauge-panel-settings.png)
Alt text: Required, describes the image content
Store in the nearest images/ subdirectory
Reference with relative paths: ![alt](images/filename.png)

Sidebar Ordering

Folder Ordering

Use _category_.json in each folder:

{
  "label": "Panels",
  "position": 3,
  "link": {
    "type": "generated-index",
    "description": "Lichtblick visualization panels."
  }
}

Page Ordering

Use sidebar_position in frontmatter to control page order within a folder. If not set, Docusaurus orders alphabetically by filename.

Cross-Referencing

Link from panel docs to message schemas: [Raw Image](../message-schemas/raw-image.md)
Link from docs to guides: [Create Custom Panel](/guides/create-custom-panel)
Link from guides to docs: [3D Panel](/docs/visualization/panels/3d-panel)

Markdownlint Rules

This project uses markdownlint-cli2. Key disabled rules (see .markdownlint-cli2.jsonc):

MD013 (line length): Disabled — tables can be wide
MD033 (inline HTML): Disabled — MDX compatibility
MD025 (single top-level heading): Disabled — Docusaurus frontmatter
MD024 (duplicate headings): Allowed in sibling sections only
MD001 (heading increment): Disabled — intentional level skips in existing docs

Run yarn lint:md to validate before committing.

name: docusaurus-conventions description: Formatting rules, page structure templates, and Docusaurus-specific conventions for the Lichtblick documentation site.