diff --git a/docs/contributing_zh.md b/docs/contributing_zh.md new file mode 100644 index 0000000..2ec2f04 --- /dev/null +++ b/docs/contributing_zh.md @@ -0,0 +1,186 @@ +# 贡献指南 + +感谢你对 **OpenWebUI Extras** 的兴趣!我们欢迎各种形式的贡献,包括插件、提示词、文档等。 + +--- + +## 🤝 如何贡献 + +### 1. 分享提示词 + +如果你有实用的提示词想要分享: + +1. 浏览 `prompts/` 目录并找到合适的分类 +2. 如果没有合适的分类,可以新建一个文件夹 +3. 创建一个新的 `.md` 文件来编写你的提示词 +4. 提交 Pull Request + +#### 提示词格式 + +```markdown +# 提示词名称 + +简短描述这个提示词的功能。 + +## 使用场景 + +说明何时使用这个提示词。 + +## 提示词内容 + +\```text +你的提示词内容... +\``` + +## 使用技巧 + +使用这个提示词的一些建议和技巧。 +``` + +--- + +### 2. 开发插件 + +如果你开发了一个 OpenWebUI 插件: + +#### 插件元数据 + +确保你的插件包含完整的元数据: + +```python +""" +title: 插件名称 +author: 你的名字 +version: 0.1.0 +description: 简短描述插件的功能 +""" +``` + +#### 目录结构 + +将插件放在合适的目录下: + +- `plugins/actions/` - Action 插件(消息下方的按钮) +- `plugins/filters/` - Filter 插件(消息处理) +- `plugins/pipes/` - Pipe 插件(自定义模型) +- `plugins/pipelines/` - Pipeline 插件(复杂工作流) + +#### 文档 + +请为你的插件提供文档: + +- `README.md` - 英文文档 +- `README_CN.md` - 中文文档(可选但推荐) + +文档应包含: + +- 功能描述 +- 安装步骤 +- 配置选项 +- 使用示例 +- 故障排除指南 + +--- + +### 3. 改进文档 + +发现错误或想要改进文档? + +1. Fork 仓库 +2. 在 `docs/` 目录下进行修改 +3. 提交 Pull Request + +--- + +## 🛠️ 开发规范 + +### 代码风格 + +- **Python**:遵循 [PEP 8](https://peps.python.org/pep-0008/) 规范 +- **注释**:为复杂逻辑添加注释 +- **命名**:使用清晰、描述性的名称 + +### 测试 + +提交前请确保: + +1. 在本地 OpenWebUI 环境中测试插件 +2. 验证所有功能按文档所述正常工作 +3. 检查边界情况和错误处理 + +### 提交信息 + +使用清晰、描述性的提交信息: + +``` +Add: 智能思维导图 action 插件 +Fix: 上下文压缩 token 计数问题 +Update: 插件开发指南添加新示例 +``` + +--- + +## 📝 提交 Pull Request + +### 详细步骤 + +1. **Fork** 本仓库 +2. **克隆**你的 fork 到本地 +3. **创建**新分支: + ```bash + git checkout -b feature/amazing-feature + ``` +4. **进行**修改 +5. **提交**你的修改: + ```bash + git commit -m 'Add: Amazing feature' + ``` +6. **推送**到你的分支: + ```bash + git push origin feature/amazing-feature + ``` +7. **创建** Pull Request + +### PR 检查清单 + +- [ ] 代码遵循项目风格指南 +- [ ] 包含/更新了文档 +- [ ] 插件已在本地测试通过 +- [ ] 提交信息清晰 +- [ ] PR 描述说明了所做的更改 + +--- + +## 🐛 报告问题 + +发现了 bug?请创建 issue 并包含以下信息: + +1. **描述**:清晰描述问题 +2. **复现步骤**:如何触发这个问题 +3. **预期行为**:应该发生什么 +4. **实际行为**:实际发生了什么 +5. **环境信息**:OpenWebUI 版本、浏览器、操作系统 + +--- + +## 💡 功能请求 + +有新想法?我们很乐意听取! + +1. 先检查是否已有类似的 issue +2. 创建新 issue 并添加 "enhancement" 标签 +3. 描述你的想法和使用场景 + +--- + +## 📄 许可证 + +通过贡献,你同意你的贡献将使用与项目相同的许可证。 + +--- + +## 🙏 感谢 + +每一份贡献,无论大小,都有助于让 OpenWebUI Extras 变得更好。感谢你成为我们社区的一员! + +[:fontawesome-brands-github: 在 GitHub 上查看](https://github.com/Fu-Jie/awesome-openwebui){ .md-button .md-button--primary } diff --git a/docs/development/documentation-guide.md b/docs/development/documentation-guide.md new file mode 100644 index 0000000..a0176bc --- /dev/null +++ b/docs/development/documentation-guide.md @@ -0,0 +1,328 @@ +# Documentation Writing Guide + +This guide explains how to write and contribute documentation for OpenWebUI Extras. + +--- + +## Overview + +Our documentation is built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) 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 + +```bash +# 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: + +```markdown +# Plugin Name + +Action +v1.0.0 + +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: + +```markdown +!!! 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 + +```markdown +??? question "Frequently asked question?" + This is the answer. + +???+ note "Open by default" + This section is expanded by default. +``` + +### Code Blocks + +````markdown +```python title="example.py" linenums="1" +def hello(): + print("Hello, World!") +``` +```` + +### Tabs + +```markdown +=== "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](https://pictogrammers.com/library/mdi/). + +### Icon Sizing + +```markdown +:material-brain:{ .lg .middle } Large icon +``` + +--- + +## Category Badges + +Use these badges for plugin types: + +```markdown +Action +Filter +Pipe +Pipeline +``` + +--- + +## Tables + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Value 1 | Value 2 | Value 3 | +``` + +For better alignment: + +```markdown +| Left | Center | Right | +|:-----|:------:|------:| +| L | C | R | +``` + +--- + +## Grid Cards + +Create card layouts for navigation: + +```markdown +
+ +- :material-icon:{ .lg .middle } **Card Title** + + --- + + Card description goes here. + + [:octicons-arrow-right-24: Link Text](link.md) + +
+``` + +--- + +## Links + +### Internal Links + +```markdown +[Link Text](../path/to/page.md) +``` + +### External Links + +```markdown +[Link Text](https://example.com){ target="_blank" } +``` + +### Button Links + +```markdown +[Button Text](link.md){ .md-button } +[Primary Button](link.md){ .md-button .md-button--primary } +``` + +--- + +## Images + +```markdown +![Alt text](path/to/image.png) + + +![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](https://www.mkdocs.org/) +- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) +- [Markdown Guide](https://www.markdownguide.org/) diff --git a/docs/development/index.md b/docs/development/index.md index 91e32ef..20824c7 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -16,6 +16,14 @@ Learn how to develop plugins and contribute to OpenWebUI Extras. [:octicons-arrow-right-24: Read the Guide](plugin-guide.md) +- :material-file-document-edit:{ .lg .middle } **Documentation Guide** + + --- + + Learn how to write and contribute documentation using MkDocs and Material theme. + + [:octicons-arrow-right-24: Read the Guide](documentation-guide.md) + - :material-github:{ .lg .middle } **Contributing** --- diff --git a/docs/index.md b/docs/index.md index 97d719d..6a3c9d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -81,7 +81,7 @@ hide: [:octicons-arrow-right-24: Learn More](plugins/actions/knowledge-card.md) -- :material-compress:{ .lg .middle } **Async Context Compression** +- :material-arrow-collapse-vertical:{ .lg .middle } **Async Context Compression** --- diff --git a/docs/index.zh.md b/docs/index.zh.md new file mode 100644 index 0000000..48b2e18 --- /dev/null +++ b/docs/index.zh.md @@ -0,0 +1,126 @@ +--- +hide: + - navigation + - toc +--- + +# 欢迎来到 OpenWebUI Extras + +
+
+ +# 🚀 增强你的 OpenWebUI 体验 + +**OpenWebUI Extras** 是一个精心整理的插件、提示词和增强功能集合,旨在扩展 [OpenWebUI](https://github.com/open-webui/open-webui) 的功能。 + +[开始使用 :material-arrow-right:](#快速导航){ .md-button .md-button--primary } +[在 GitHub 上查看 :fontawesome-brands-github:](https://github.com/Fu-Jie/awesome-openwebui){ .md-button } + +
+
+ +--- + +## 快速导航 + +
+ +- :material-puzzle:{ .lg .middle } **插件中心** + + --- + + 浏览我们强大的插件集合,包括 Actions、Filters、Pipes 和 Pipelines,以增强你的 AI 交互体验。 + + [:octicons-arrow-right-24: 探索插件](plugins/index.md) + +- :material-message-text:{ .lg .middle } **提示词库** + + --- + + 发现精心制作的提示词,涵盖编程、写作、营销等领域。即复即用。 + + [:octicons-arrow-right-24: 浏览提示词](prompts/index.md) + +- :material-tools:{ .lg .middle } **增强功能** + + --- + + 学习优化 OpenWebUI 体验的技巧和窍门,包括高级配置和自定义选项。 + + [:octicons-arrow-right-24: 查看指南](enhancements/index.md) + +- :material-book-open-page-variant:{ .lg .middle } **开发指南** + + --- + + 从入门教程到高级模式,全面的插件开发指南。 + + [:octicons-arrow-right-24: 开始开发](development/index.md) + +
+ +--- + +## 精选插件 + +
+ +- :material-brain:{ .lg .middle } **智能思维导图** + + --- + + 智能分析文本内容,生成交互式思维导图,便于可视化理解。 + + [:octicons-arrow-right-24: 了解更多](plugins/actions/smart-mind-map.md) + +- :material-card-text:{ .lg .middle } **知识卡片** + + --- + + 快速生成精美的学习记忆卡片,非常适合学习和快速记忆。 + + [:octicons-arrow-right-24: 了解更多](plugins/actions/knowledge-card.md) + +- :material-arrow-collapse-vertical:{ .lg .middle } **异步上下文压缩** + + --- + + 通过智能摘要减少长对话中的 token 消耗,同时保持对话连贯性。 + + [:octicons-arrow-right-24: 了解更多](plugins/filters/async-context-compression.md) + +
+ +--- + +## 快速入门 + +### 使用提示词 + +1. 浏览[提示词库](prompts/library.md)并选择一个提示词 +2. 点击**复制**按钮将提示词复制到剪贴板 +3. 在 OpenWebUI 中,点击输入框上方的"提示词"按钮 +4. 粘贴内容并保存 + +### 使用插件 + +1. 浏览[插件中心](plugins/index.md)并下载插件文件(`.py`) +2. 打开 OpenWebUI **管理面板** → **设置** → **插件** +3. 点击上传按钮并选择 `.py` 文件 +4. 刷新页面并在聊天设置中启用插件 + +--- + +## 参与贡献 + +我们欢迎各种形式的贡献!无论是新插件、实用的提示词,还是文档改进。 + +[:octicons-heart-fill-24:{ .heart } 查看贡献指南](contributing_zh.md){ .md-button } + +--- + + diff --git a/docs/plugins/actions/index.md b/docs/plugins/actions/index.md index b787f71..f907af2 100644 --- a/docs/plugins/actions/index.md +++ b/docs/plugins/actions/index.md @@ -27,6 +27,16 @@ Actions are interactive plugins that: [:octicons-arrow-right-24: Documentation](smart-mind-map.md) +- :material-chart-bar:{ .lg .middle } **Smart Infographic** + + --- + + Transform text into professional infographics using AntV visualization engine with various templates. + + **Version:** 1.0.0 + + [:octicons-arrow-right-24: Documentation](smart-infographic.md) + - :material-card-text:{ .lg .middle } **Knowledge Card** --- diff --git a/docs/plugins/actions/smart-infographic.md b/docs/plugins/actions/smart-infographic.md new file mode 100644 index 0000000..82f327b --- /dev/null +++ b/docs/plugins/actions/smart-infographic.md @@ -0,0 +1,107 @@ +# Smart Infographic + +Action +v1.0.0 + +An AntV Infographic engine powered plugin that transforms long text into professional, beautiful infographics with a single click. + +--- + +## Overview + +The Smart Infographic plugin uses AI to analyze text content and generate professional infographics using the AntV visualization engine. It automatically extracts key points and structures them into visually appealing charts and diagrams. + +## Features + +- :material-robot: **AI-Powered Transformation**: Automatically analyzes text logic, extracts key points, and generates structured charts +- :material-palette: **Professional Templates**: Includes various AntV official templates: Lists, Trees, Mindmaps, Comparison Tables, Flowcharts, and Statistical Charts +- :material-magnify: **Auto-Icon Matching**: Built-in logic to search and match the most relevant Material Design Icons based on content +- :material-download: **Multi-Format Export**: Download your infographics as **SVG**, **PNG**, or **Standalone HTML** file +- :material-theme-light-dark: **Theme Support**: Supports Dark/Light modes, auto-adapts theme colors +- :material-cellphone-link: **Responsive Design**: Generated charts look great on both desktop and mobile devices + +--- + +## Installation + +1. Download the plugin file: [`infographic.py`](https://github.com/Fu-Jie/awesome-openwebui/tree/main/plugins/actions/infographic) +2. Upload to OpenWebUI: **Admin Panel** → **Settings** → **Functions** +3. Configure plugin settings (optional) +4. Enable the plugin + +--- + +## Supported Template Types + +| Category | Template Name | Use Case | +|:---------|:--------------|:---------| +| **Lists & Hierarchy** | `list-grid`, `tree-vertical`, `mindmap` | Features, Org Charts, Brainstorming | +| **Sequence & Relation** | `sequence-roadmap`, `relation-circle` | Roadmaps, Circular Flows, Steps | +| **Comparison & Analysis** | `compare-binary`, `compare-swot`, `quadrant-quarter` | Pros/Cons, SWOT, Quadrants | +| **Charts & Data** | `chart-bar`, `chart-line`, `chart-pie` | Trends, Distributions, Metrics | + +--- + +## Usage + +1. Enter your text content in the chat +2. Click the **Infographic** button (📊 icon) in the message action bar +3. Wait for AI to analyze and generate the infographic +4. Preview the result and use the download buttons to save + +--- + +## Configuration + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `SHOW_STATUS` | boolean | `true` | Show real-time AI analysis and generation status | +| `MODEL_ID` | string | `""` | Specify the LLM model for text analysis. If empty, uses current chat model | +| `MIN_TEXT_LENGTH` | integer | `100` | Minimum characters required to trigger analysis | +| `CLEAR_PREVIOUS_HTML` | boolean | `false` | Whether to clear previous charts | +| `MESSAGE_COUNT` | integer | `1` | Number of recent messages to use for analysis | + +--- + +## Syntax Example (Advanced Users) + +You can also input infographic syntax directly for rendering: + +```infographic +infographic list-grid +data + title 🚀 Plugin Benefits + desc Why use the Smart Infographic plugin + items + - label Fast Generation + desc Convert text to charts in seconds + - label Beautiful Design + desc Uses AntV professional design standards +``` + +--- + +## Requirements + +!!! note "Prerequisites" + - OpenWebUI v0.3.0 or later + - No additional Python packages required (uses built-in OpenWebUI dependencies) + +--- + +## Troubleshooting + +??? question "Infographic not generating?" + Make sure your text content is at least 100 characters (configurable via `MIN_TEXT_LENGTH`). + +??? question "Template not matching content?" + The AI automatically selects the best template based on content structure. For specific templates, you can use the advanced syntax. + +??? question "Export not working?" + Ensure your browser supports HTML5 Canvas and SVG. Try refreshing the page. + +--- + +## Source Code + +[:fontawesome-brands-github: View on GitHub](https://github.com/Fu-Jie/awesome-openwebui/tree/main/plugins/actions/infographic){ .md-button } diff --git a/docs/plugins/filters/async-context-compression.md b/docs/plugins/filters/async-context-compression.md index cb1b1e8..3498585 100644 --- a/docs/plugins/filters/async-context-compression.md +++ b/docs/plugins/filters/async-context-compression.md @@ -25,7 +25,7 @@ This is especially useful for: ## Features -- :material-compress: **Smart Compression**: AI-powered context summarization +- :material-arrow-collapse-vertical: **Smart Compression**: AI-powered context summarization - :material-clock-fast: **Async Processing**: Non-blocking background compression - :material-memory: **Context Preservation**: Keeps important information - :material-currency-usd-off: **Cost Reduction**: Minimize token usage diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 1d033f5..0528df1 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -49,6 +49,7 @@ OpenWebUI supports four types of plugins, each serving a different purpose: | Plugin | Type | Description | Version | |--------|------|-------------|---------| | [Smart Mind Map](actions/smart-mind-map.md) | Action | Generate interactive mind maps from text | 0.7.2 | +| [Smart Infographic](actions/smart-infographic.md) | Action | Transform text into professional infographics | 1.0.0 | | [Knowledge Card](actions/knowledge-card.md) | Action | Create beautiful learning flashcards | 0.2.0 | | [Export to Excel](actions/export-to-excel.md) | Action | Export chat history to Excel files | 1.0.0 | | [Summary](actions/summary.md) | Action | Text summarization tool | 1.0.0 | diff --git a/mkdocs.yml b/mkdocs.yml index cc05e71..017d14c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,6 +69,42 @@ theme: plugins: - search: separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' + - i18n: + docs_structure: suffix + fallback_to_default: true + reconfigure_material: true + reconfigure_search: true + languages: + - locale: en + default: true + name: English + build: true + - locale: zh + name: 简体中文 + build: true + nav_translations: + Home: 首页 + Plugins: 插件 + Actions: 动作 + Filters: 过滤器 + Pipes: 管道 + Pipelines: 流水线 + Prompts: 提示词 + Enhancements: 增强功能 + Development: 开发指南 + Contributing: 贡献指南 + Plugin Development Guide: 插件开发指南 + Documentation Guide: 文档编写指南 + Smart Mind Map: 智能思维导图 + Smart Infographic: 智能信息图 + Knowledge Card: 知识卡片 + Export to Excel: 导出到 Excel + Summary: 摘要 + Async Context Compression: 异步上下文压缩 + Context Enhancement: 上下文增强 + Gemini Manifold Companion: Gemini Manifold 伴侣 + Gemini Manifold: Gemini Manifold + MoE Prompt Refiner: MoE 提示词优化器 - minify: minify_html: true @@ -146,6 +182,7 @@ nav: - Actions: - plugins/actions/index.md - Smart Mind Map: plugins/actions/smart-mind-map.md + - Smart Infographic: plugins/actions/smart-infographic.md - Knowledge Card: plugins/actions/knowledge-card.md - Export to Excel: plugins/actions/export-to-excel.md - Summary: plugins/actions/summary.md @@ -169,4 +206,5 @@ nav: - Development: - development/index.md - Plugin Development Guide: development/plugin-guide.md + - Documentation Guide: development/documentation-guide.md - Contributing: contributing.md diff --git a/requirements.txt b/requirements.txt index 31d8bc9..c880fae 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,5 +8,5 @@ mkdocs-material>=9.5.0 # Plugins mkdocs-minify-plugin>=0.7.0 -# Optional: Multi-language support (uncomment if needed) -# mkdocs-static-i18n>=1.0.0 +# Multi-language support +mkdocs-static-i18n>=1.0.0