Skip to main content

Contributing to Rspamd Documentation

This guide explains how to contribute to the Rspamd documentation website, which is built using Docusaurus.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js version 18.0 or above
  • Git
  • A text editor or IDE of your choice
  • A GitHub account

Getting Started

1. Fork and Clone the Repository

  1. Fork the docs.rspamd.com repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR-USERNAME/docs.rspamd.com.git
cd docs.rspamd.com

2. Install Dependencies

Install the required Node.js packages:

npm install

3. Run the Development Server

Start the local development server:

npm start

This will start a local server at http://localhost:3000. The site will automatically reload when you make changes to the documentation.

Project Structure

docs.rspamd.com/
├── blog/ # Blog posts
├── docs/ # Documentation files
│ ├── about/ # About Rspamd
│ ├── configuration/ # Configuration guides
│ ├── modules/ # Module documentation
│ ├── tutorials/ # Tutorial content
│ └── ... # Other documentation sections
├── src/ # Custom components and pages
├── static/ # Static assets (images, files)
├── docusaurus.config.js # Site configuration
├── sidebars.js # Sidebar navigation configuration
└── package.json # Project dependencies

Writing Documentation

Creating New Pages

  1. Add new Markdown files in the appropriate directory under docs/
  2. Use the following frontmatter format at the beginning of each file:
---
title: Your Page Title
description: Brief description of the page content
---

# Your Page Title

Your content here...

Formatting Guidelines

  • Use Markdown for all documentation
  • Follow the existing structure and naming conventions
  • Keep paragraphs concise and focused
  • Use code blocks with appropriate language highlighting:
-- Lua example
local function example()
return "Hello, Rspamd!"
end

Adding Images

  1. Place images in the static/img/ directory
  2. Reference them in your Markdown:
![Alt text](/img/your-image.png)

Docusaurus automatically handles internal links. Use relative paths without file extensions:

<!-- Link to another doc -->
[Configuration Guide](/configuration/basic)

<!-- Link to a section in another doc -->
[Worker Configuration](/configuration/workers#normal-worker)

External links work as usual in Markdown:

[Rspamd GitHub](https://github.com/rspamd/rspamd)

Advanced Features

Admonitions

Use admonitions to highlight important information:

:::note
This is a note
:::

:::tip
This is a tip
:::

:::warning
This is a warning
:::

:::danger
This is a danger warning
:::

:::info
This is an info box
:::

Mermaid Diagrams

You can include Mermaid diagrams directly in your Markdown:

```mermaid
graph TD
A[Client] -->|Sends Email| B[MTA]
B --> C[Rspamd]
C -->|Scan Result| B
```

Code Tabs

For showing code in multiple languages or configurations:

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

<Tabs>
<TabItem value="lua" label="Lua" default>

```lua
-- Lua configuration
```

</TabItem>
<TabItem value="ucl" label="UCL">

```ucl
# UCL configuration
```

</TabItem>
</Tabs>

Testing Your Changes

Local Testing

  1. Run the development server and check your changes at http://localhost:3000
  2. Navigate through your new/modified pages
  3. Test all links to ensure they work correctly
  4. Check that images load properly
  5. Verify code syntax highlighting

Building for Production

To test the production build locally:

npm run build
npm run serve

This will build the static site and serve it locally, allowing you to test the final output.

Submitting Your Contribution

1. Commit Your Changes

git add .
git commit -m "Add/Update: Brief description of your changes"

2. Push to Your Fork

git push origin main

3. Create a Pull Request

  1. Go to your fork on GitHub
  2. Click "Pull Request"
  3. Provide a clear description of your changes
  4. Reference any related issues
  5. Submit the pull request

Style Guide

Writing Style

  • Use clear, concise language
  • Write in the present tense
  • Use active voice when possible
  • Define technical terms on first use
  • Include practical examples

File Naming

  • Use lowercase letters
  • Separate words with underscores (e.g., getting_started.md)
  • Be descriptive but concise

Commit Messages

  • Use present tense ("Add feature" not "Added feature")
  • Be descriptive but concise
  • Reference issues when applicable

Common Tasks

Updating the Sidebar

Edit sidebars.js to modify the navigation structure:

module.exports = {
docs: [
{
type: 'category',
label: 'Your Category',
items: ['your-doc-id', 'another-doc-id'],
},
],
};

Adding to the Changelog

Changelogs are managed in the changelogs/ directory. Follow the existing format when adding new entries.

Getting Help

If you need assistance:

  1. Check the Docusaurus documentation
  2. Open an issue on the docs.rspamd.com repository
  3. Join the Rspamd community discussions

License

By contributing to the Rspamd documentation, you agree that your contributions will be licensed under the same license as the project.