Documentation Writing Guide¶

This guide explains how to write and contribute documentation for OpenWebUI Extras.

Overview¶

Our documentation is built with MkDocs and the Material for MkDocs theme. Understanding the basics of Markdown and MkDocs will help you contribute effectively.

Getting Started¶

Prerequisites¶

Python 3.8 or later
Git

Local Setup¶

# Clone the repository
git clone https://github.com/Fu-Jie/awesome-openwebui.git
cd awesome-openwebui

# Install dependencies
pip install -r requirements.txt

# Start the development server
mkdocs serve

Visit http://localhost:8000 to preview the documentation.

Documentation Structure¶

docs/
├── index.md              # Homepage
├── contributing.md       # Contribution guide
├── plugins/              # Plugin documentation
│   ├── index.md          # Plugin center overview
│   ├── actions/          # Action plugins
│   ├── filters/          # Filter plugins
│   ├── pipes/            # Pipe plugins
│   └── pipelines/        # Pipeline plugins
├── prompts/              # Prompt library
├── enhancements/         # Enhancement guides
├── development/          # Development guides
└── stylesheets/          # Custom CSS

Writing Plugin Documentation¶

Template¶

Use this template for new plugin documentation:

# Plugin Name

<span class="category-badge action">Action</span>
<span class="version-badge">v1.0.0</span>

Brief description of what the plugin does.

---

## Overview

Detailed explanation of the plugin's purpose and functionality.

## Features

- :material-icon-name: **Feature 1**: Description
- :material-icon-name: **Feature 2**: Description

---

## Installation

1. Download the plugin file
2. Upload to OpenWebUI
3. Configure settings
4. Enable the plugin

---

## Usage

Step-by-step usage instructions.

---

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option_name` | type | `default` | Description |

---

## Requirements

!!! note "Prerequisites"
    - OpenWebUI v0.3.0 or later
    - Any additional requirements

---

## Troubleshooting

??? question "Common issue?"
    Solution to the issue.

---

## Source Code

[:fontawesome-brands-github: View on GitHub](https://github.com/Fu-Jie/awesome-openwebui/tree/main/plugins/...){ .md-button }

Markdown Extensions¶

Admonitions¶

Use admonitions to highlight important information:

!!! note "Title"
    This is a note.

!!! warning "Caution"
    This is a warning.

!!! tip "Pro Tip"
    This is a helpful tip.

!!! danger "Warning"
    This is a critical warning.

Collapsible Sections¶

??? question "Frequently asked question?"
    This is the answer.

???+ note "Open by default"
    This section is expanded by default.

Code Blocks¶

```python title="example.py" linenums="1"
def hello():
    print("Hello, World!")
```

Tabs¶

=== "Python"

    ```python
    print("Hello")
    ```

=== "JavaScript"

    ```javascript
    console.log("Hello");
    ```

Icons¶

Use Material Design Icons with the :material-icon-name: syntax:

:material-brain:
:material-puzzle:
:material-download:
:material-github:

Find more icons at Material Design Icons.

Icon Sizing¶

:material-brain:{ .lg .middle } Large icon

Category Badges¶

Use these badges for plugin types:

<span class="category-badge action">Action</span>
<span class="category-badge filter">Filter</span>
<span class="category-badge pipe">Pipe</span>
<span class="category-badge pipeline">Pipeline</span>

Tables¶

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |

For better alignment:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Grid Cards¶

Create card layouts for navigation:

<div class="grid cards" markdown>

-   :material-icon:{ .lg .middle } **Card Title**

    ---

    Card description goes here.

    [:octicons-arrow-right-24: Link Text](link.md)

</div>

Links¶

Internal Links¶

[Link Text](../path/to/page.md)

External Links¶

[Link Text](https://example.com){ target="_blank" }

Button Links¶

[Button Text](link.md){ .md-button }
[Primary Button](link.md){ .md-button .md-button--primary }

Images¶

![Alt text](path/to/image.png)

<!-- With attributes -->
![Alt text](path/to/image.png){ width="300" }