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.