---
name: rsyslog_doc
description: Guidelines for maintaining structured, RAG-optimized documentation and module metadata.
triggers:
  - doc/source/**/*.rst
---

# rsyslog_doc

This skill ensures that all documentation is consistent, discoverable, and optimized for both human readers and AI ingestion systems.

## Quick Start

1.  **Metadata Block**: Every `.rst` must have a `.. meta::` block.
2.  **Summary Slices**: Wrap intros in `.. summary-start` and `.. summary-end`.
3.  **Cross-Link**: Update `index.rst` and `doc/ai/module_map.yaml`.

## Detailed Instructions

### 1. Structured Requirements
Every documentation page must include:
- **Meta Block**:
  ```rst
  .. meta::
     :description: Brief description for SEO and RAG.
     :keywords: rsyslog, module, config, ...
  ```
- **Summary Slices**: Essential for RAG (Retrieval-Augmented Generation).
  ```rst
  .. summary-start
  Concise summary of what this module/feature does.
  .. summary-end
  ```

---
> [!IMPORTANT]
> **Trigger Side-Effect**: If you add, move, or remove any `.rst` file, YOU MUST follow the [`rsyslog_doc_dist`](../rsyslog_doc_dist/SKILL.md) skill to update `doc/Makefile.am` and run the **extended distribution check**.

> [!IMPORTANT]
> **Sample Config Security Review**: If you add or materially update a sample
> rsyslog configuration, you MUST review that specific configuration for
> security posture before finishing the documentation change. Check whether the
> example exposes listeners, weakens authentication or TLS, writes to sensitive
> paths, follows unsafe file/link behavior, uses overly broad permissions,
> enables compatibility fallbacks, or recommends defaults that are unsuitable
> for new deployments. Use `doc/ai/security_triage_rubric.md` to classify any
> concern as a confirmed issue, potential issue, hardening, or not actionable.
> If this review exposes vulnerable or unsafe code behavior, do not treat it as
> documentation-only work: either fix the code in the same change when the scope
> is clear and bounded, or record the implementation follow-up with enough
> evidence for maintainers to reproduce and prioritize it.

### 2. Module Documentation
- **Parameters**: Use the `include` directive to pull parameter details from `doc/source/reference/parameters/`.
- **Anchors**: Use explicit anchors (e.g., `.. _parameter_name:`) for consistent linking.
- **Templates**: Reference `doc/ai/templates/template-module.rst`.

### 3. Metadata Files
- **Plugins/Contrib**: Maintain `MODULE_METADATA.yaml` in the module directory.
- **Built-in Tools**: Update `tools/MODULE_METADATA.json`.
- **Required Keys**: `support_status`, `maturity_level`, `primary_contact`, `last_reviewed`.

### 4. Validation
- **Build Docs**: For rendered user-facing documentation changes under
  `doc/source/**`, or Sphinx support files that affect that tree, run a
  high-concurrency HTML build:
  `./doc/tools/build-doc-linux.sh --clean --format html --jobs "${RSYSLOG_LOCAL_DOC_JOBS:-$(nproc)}"`.
  Add `--strict` for larger, structural, navigation-heavy, or warning-sensitive
  documentation edits.
- Internal docs that are not rendered into the user manual, such as `doc/ai/**`,
  repository agent guides, and skill files, do not require a Sphinx docs build
  unless they also change rendered Sphinx inputs.
- **json-formatter**: Run `make -j16 json-formatter` to update the RAG knowledge base.
- **Mermaid**: Ensure Mermaid diagrams have a blank line after the directive and quoted labels.

### 5. Style & Tone
- Follow the **Doc Assistant Prompt**: `ai/rsyslog_doc_assistant/base_prompt.txt`.
- Use canonical terminology from `doc/ai/terminology.md`.

## Related Skills
- `rsyslog_module`: For technical details to include in docs.
- `rsyslog_commit`: For doc-only commit message rules.
