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:
Getting Started
1. Fork and Clone the Repository
- Fork the docs.rspamd.com repository on GitHub
- 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
- Add new Markdown files in the appropriate directory under
docs/
- 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
- Place images in the
static/img/
directory - Reference them in your Markdown:

Internal Links
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
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
- Run the development server and check your changes at
http://localhost:3000
- Navigate through your new/modified pages
- Test all links to ensure they work correctly
- Check that images load properly
- 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
- Go to your fork on GitHub
- Click "Pull Request"
- Provide a clear description of your changes
- Reference any related issues
- 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:
- Check the Docusaurus documentation
- Open an issue on the docs.rspamd.com repository
- 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.