Documentation Standards & Style Guide

This guide establishes the professional standards for all documentation in this repository. Every pull request is evaluated against these rules to ensure consistency, accuracy, and a world-class developer experience.

---

1. Frontmatter & SEO

Every .md or .mdx file must begin with a YAML frontmatter block.

Required Fields

Field	Required	Description
title	✅ Yes	Clear, action-oriented page title
description	✅ Yes	120–160 character summary for SEO
tags	✅ Yes	List of relevant tags (e.g., [docker, install, setup])
sidebar_label	✅ Yes	Concise label shown in the navigation menu
sidebar_position	⬜ Optional	Integer controlling the order within a sidebar group
slug	⬜ Optional	Custom URL path (e.g., /stream/offline-install)

note

We are migrating from keywords to tags. Docusaurus uses tags to automatically generate taxonomy pages and improve internal search relevance. New files must use tags. Any edit to an existing file must also migrate keywords to tags in the same PR.

Example

---
title: Stream Offline Installation
sidebar_label: Offline Installation
sidebar_position: 4
description: Install Plate Recognizer Stream on a machine without internet access using a Docker image archive.
tags: [stream, install, offline, docker]
---

---

2. Linking Architecture

Links are the backbone of our documentation. Incorrect links break the build or degrade user trust.

Internal Page Links

• Rule: Must include the /docs/ prefix and the file extension (.md or .mdx).
• Correct: [Docker Installation](/docs/docker.md)
• Incorrect: [Docker Installation](./docker) (Missing extension and root prefix).

Internal Anchor Links

• Rule: Link to a specific header using the slugified header text.
• Correct: [Troubleshoot](/docs/parkpow/on-premise.mdx#common-issues)

External Links

• Rule: Use full HTTPS URLs.
• Correct: [Docusaurus](https://docusaurus.io/)

Image Links (Assets)

• Rule: Use relative paths starting from the current file's directory to the assets folder. Use PNG format where possible.
• Correct (from docs/parkpow/doc.md): ![Alt Text](../assets/parkpow/image.png)
• Correct (from docs/stream/integrations/doc.md): ![Alt Text](../../assets/stream/image.png)

---

3. Formatting & Structure

Headings

• Use exactly one H1 (#) at the top of the file.
• Use H2 (##) for main sections, followed by a horizontal rule (---) if the section is large.
• Use H3 (###) for sub-sections or steps in a guide.

Numbered Steps

Use Markdown native numbered lists (1.). Sub-items (code blocks, notes) must be indented with 3 spaces to stay attached to their step.

1. Download the image.

   ```shell
   docker pull platerecognizer/alpr-stream

1. Save the image as a tar archive.

   docker save platerecognizer/alpr-stream > alpr-stream.tar

:::note
Do **not** use bold manual numbering (`**1)**`). Always use `1.` so Markdown renders it automatically.
:::

### Paragraphs & Scannability
- Paragraphs must not exceed **4 sentences**.
- Use bulleted lists for requirements or features.
- Avoid "Wall of Text". Use code blocks or admonitions to break visual monotony.

### Summary Section
Pages with 5 or more H2 sections (reference pages, configuration guides, system requirements) **must** end with a `## Summary` section containing a bullet list of key takeaways.

```markdown
## Summary

- **Use H264 for best performance.** H265 requires more processing power.
- **Ensure CPU meets Passmark requirements.** Use the Hardware Recommendation tool.
- **Allocate enough RAM** based on video resolution and MMC usage.

---

4. Writing Style & Tone

Active Voice (Imperative)

• Rule: Address the reader directly. Tell them what to do.
• Correct: "Install the Docker container."
• Incorrect: "The Docker container should be installed." / "We will install the container."

Inclusive & Professional Language

• Use American English.
• Avoid jargon without explanation.
• Use On-premises (hyphenated, lowercase "premises") instead of "On-Premise" or "Local only".

---

5. Docusaurus Components (Admonitions)

Use admonitions to highlight critical information. Do not overuse them — maximum one per logical section.

Type	Use when	Do NOT use for
:::tip	Pro-tips, shortcuts, recommended alternatives	Generic info that doesn't save effort
:::info	Supplementary context the reader may want	Required information (use :::note instead)
:::note	Reminders, caveats, soft requirements	Destructive or risky actions
:::warning	Potential data loss, backup reminders, irreversible config changes	Low-risk notes
:::danger	Destructive actions (e.g., uninstall, license reset, docker compose down)	Anything recoverable
:::caution	Actions that take significant time or have delayed effects	Instant actions

---

6. Code Blocks

Language Tags

Every code block must have a language tag. Common tags: bash, shell, json, yaml, ini, env, powershell, csv, mdx, markdown.

Code Block Titles

For installation and configuration guides, add a title to code blocks to describe what the command does:

```shell title="Pull the Stream Docker image"
docker pull platerecognizer/alpr-stream
```

Placeholders

• Use UPPERCASE_WITH_UNDERSCORES for values the user must replace.
• Correct: url = http://YOUR_IP_ADDRESS:8002
• Every placeholder must be accompanied by a description or link explaining where to obtain the value. See §15.

JSON with Comments

• JSON comments (// comment) are accepted in documentation to annotate response examples.
• JSON comments are forbidden in code blocks that represent a real API payload or config file a user will copy-paste.

---

7. Terminology Map

Use these exact terms for consistency:

Term	Rule
ALPR	All uppercase
Plate Recognizer	Capitalized, two words
ParkPow	One word, camel case
Stream	Capitalized
On-premises	Hyphenated, lowercase "premises". Not "On-Premise" or "On-Premises"
LICENSE_KEY	Always uppercase, monospace (LICENSE_KEY)
TOKEN	Always uppercase, monospace (TOKEN)

---

8. Multi-language & OS Tabs

When providing examples across multiple programming languages and operating systems, use the following nested <Tabs> structure.

Template

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

<Tabs defaultValue="shell" values={[
      { label: 'Shell', value: 'shell' },
      { label: 'Ruby', value: 'ruby' },
      { label: 'Python', value: 'python' },
      { label: 'JavaScript', value: 'javascript' },
      { label: 'C#', value: 'csharp' },
      { label: 'PHP', value: 'php' },
      { label: 'Java', value: 'java' },
      { label: 'C++', value: 'cpp' },
    ]}>

<TabItem value="shell">

<Tabs defaultValue="linux" values={[
      { label: 'Linux', value: 'linux' },
      { label: 'Windows', value: 'windows' },
    ]}>
    <TabItem value="linux">

```shell
# Linux command
```

    </TabItem>
    <TabItem value="windows">

```powershell
# Windows command
```

    </TabItem>
</Tabs>

</TabItem>

<TabItem value="python">

```python
# Python code
```

</TabItem>

{/* Add other TabItems for Ruby, JS, etc. */}

</Tabs>

---

9. Quick Links for Large Documents

For large documents with many sections (e.g., FAQ, Integrations, Configurations), provide a "Quick Links" or Table of Contents (TOC) at the top of the page after the intro paragraph.

For .mdx files

Use the Docusaurus TOCInline component for an automated, clean list of headers.

import TOCInline from "@theme/TOCInline";

<TOCInline toc={toc} minHeadingLevel={2} />

For .md files

Use a manual Markdown Table to map key sections to their descriptions and internal anchor links.

| Section | Description |
| ------- | ----------- |
| [Section Name](#anchor-slug) | Brief description of what this section covers. |

---

10. Page Archetypes (Required Structure)

The Agent identifies the page type based on the title or path and enforces the following structures:

A. Getting Started / Installation

• Required Sections: ## System Requirements, ## Install, ## Upgrade (if applicable), ## Uninstall (if applicable).
• Step Pattern: Use Markdown numbered lists (1.) with indented sub-blocks. See §3.
• System Requirements: Must be explicitly listed at the top or in its own section.

B. Configuration

• Level Usage: Individual parameters MUST use ### (H3) headers.
• Security: Commands involving TOKEN or LICENSE_KEY must be followed by a :::danger block reminding the user to replace placeholders.
• Speed/Networking: Large configuration files should have a specific section for speed optimization.

C. API Reference

• Required Sections: ## Authentication, ## HTTP Request, ## Parameters (Table), ## Response (JSON + Field Table).
• Endpoint Format: Use backticks for the method and URL: POST https://api...
• Tables: Every JSON response field must be documented in a Markdown table. See §13.

---

11. Versioning Documentation

Our products evolve rapidly. Use this pattern to denote new features or changes:

• Pattern: _New in version X.Y.Z._ (Italics).
• Placement: Place it immediately after the component, header, or description it refers to.

_New in version 1.58.0._

---

12. Multi-OS Line Continuations

When providing long shell commands that span multiple lines:

• Linux (bash/shell): Use the backslash \ character.
• Windows (cmd/powershell): Use the caret ^ character.

Example

# Linux
docker run \
  -d --name alpr \
  platerecognizer/alpr

# Windows
docker run ^
  -d --name alpr ^
  platerecognizer/alpr

---

13. Webhook & JSON Response Field Documentation

Any page that documents a JSON response payload with 5 or more fields must include a field reference table immediately after the JSON block.

Table Format

Field	Type	Description
camera_id	string	Unique identifier for the camera source
timestamp	string	UTC timestamp of the recognition event (ISO 8601)
results	array	List of recognized plates and vehicle data
plate	string	Recognized license plate text
score	float	Confidence score (0.0–1.0)

Rules

• Nested objects must have their own sub-table or be explained inline.
• Fields that are only present under certain conditions must be noted: Only present when dwell_time is enabled.
• Optional fields must be labeled: (optional) in the Description column.

---

14. Custom React Components

File Extension Rule

• .md files: no JSX allowed. Use only Markdown syntax and admonitions.
• .mdx files: JSX and custom components are allowed.

Import Convention

Always place import statements immediately after the frontmatter and before the H1 heading.

---
title: Example
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import TOCInline from "@theme/TOCInline";
import { Requirements } from "@site/src/components/Requirement";

# Example Page

Custom Site Components (@site/src/components/)

• Use only for genuinely interactive or data-driven content (e.g., hardware calculators, requirement selectors).
• Every custom component must have a meaningful text fallback for cases where JavaScript is unavailable.
• Document the component's purpose with a :::info admonition immediately above it.

Inline Styles

Avoid inline style={{...}} props in production documentation. Use CSS classes or Docusaurus theme variables instead.

---

15. Placeholder Documentation Rule

Every placeholder that a user must replace (YOUR_LICENSE_KEY, TARGET_URL, YOUR_API_TOKEN) must be accompanied by one of the following:

1. An inline explanation immediately after the code block:

   Replace `YOUR_LICENSE_KEY` with the key found at [app.platerecognizer.com/service/stream](https://app.platerecognizer.com/service/stream/).

2. A :::danger admonition for security-sensitive values (tokens, API keys, passwords):

   :::danger
   Replace `YOUR_API_TOKEN` with your token from [your account page](https://app.platerecognizer.com/).
   Never commit this value to source control.
   :::

3. A link to the relevant documentation section that explains the concept and where to obtain the value.

Forbidden Patterns

• A placeholder appearing in a code block with no explanation anywhere on the page.
• Using generic words like <your-key> — always use UPPERCASE_WITH_UNDERSCORES.