Fu-Jie_openwebui-extensions/docs/development/documentation-guide.md

Documentation Writing Guide

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

---

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

1. Python 3.8 or later
2. Git

Local Setup

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

# 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/openwebui-extensions/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-brain:
• :material-puzzle: :material-puzzle:
• :material-download: :material-download:
• :material-github: :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" }

---

Best Practices

Writing Style

1. Be concise: Get to the point quickly
2. Use examples: Show, don't just tell
3. Be consistent: Follow existing patterns
4. Write for beginners: Assume minimal prior knowledge

Formatting

1. Use proper heading hierarchy (H1 → H2 → H3)
2. Add horizontal rules (---) between major sections
3. Use lists for steps and features
4. Include code examples where helpful

SEO

1. Use descriptive page titles
2. Include relevant keywords naturally
3. Add meta descriptions in frontmatter if needed

---

Submitting Changes

1. Create a feature branch
2. Make your documentation changes
3. Test locally with mkdocs serve
4. Submit a pull request

---

Additional Resources

• MkDocs Documentation
• Material for MkDocs
• Markdown Guide