CONTRIBUTING.md

贡献指南

感谢你有兴趣为 JustHTMLs 做出贡献！我们欢迎各种形式的贡献，包括新工具、错误修复和文档改进。

⚠️ 重要提示
所有工具提交必须通过 GitHub Issues 进行。我们会在审核通过后，由维护者将代码合并到主仓库。

🚀 如何贡献新工具

1. 工具设计原则

在开始之前，请确保你的工具符合以下设计原则：

• 单文件 HTML - 所有 HTML、CSS 和 JavaScript 都在一个文件中
• 无构建步骤 - 不使用 React、JSX 或需要编译的技术
• 本地依赖 - 第三方库放入 assets/vendor，并提供 CDN 回退
• 保持精简 - 代码量控制在几百行以内，便于维护和理解
• 隐私优先 - 数据在浏览器本地处理，不发送到服务器

2. 创建工具文件夹

在 tools 目录下创建一个新的文件夹，文件夹名称使用小写字母和连字符，例如 json-to-yaml。

3. 创建必需文件

每个工具必须包含以下三个文件：

工具目录结构示例：

tools/
  └── json-to-yaml/
      ├── index.html       # 工具详情页（介绍页面）
      ├── app.html         # 工具实体页（实际运行的工具）
      └── tool.json        # 工具元数据（可选，用于扩展信息）

4. 编写工具代码

步骤 1：创建 app.html

这是工具的核心功能页面，应该是一个完全独立的 HTML 文件，包含所有内联的 CSS 和 JavaScript。

步骤 2：创建 index.html

这是工具的介绍页面，用于展示工具的功能、使用方法、作者信息等。

步骤 3：测试工具

在浏览器中直接打开 app.html，确保所有功能正常工作。

5. 提交工具

通过 GitHub Issues 提交你的工具：

1. 点击下方按钮创建新的 Issue
2. 选择"工具提交"模板
3. 填写工具信息
4. 将工具代码完整粘贴到 Issue 中（或提供 Gist 链接）
5. 等待维护者审核

创建工具提交 Issue

📄 工具元数据规范

提交工具时，请在 Issue 中提供以下信息：

必需信息：

• 工具 ID - 唯一标识符（如：json-to-yaml）
• 工具名称 - 显示名称（如：JSON 转 YAML）
• 分类 - 选择一个现有分类或建议新分类
• 标签 - 3-5个相关标签
• 简短描述 - 一句话描述工具功能
• 详细描述 - 详细说明工具用途和特点
• 图标 - 选择一个 Emoji 作为工具图标
• 颜色 - 主题颜色（如：#6366f1）
• 作者信息 - 名称和 GitHub/个人链接

📋 工具分类

当前支持的分类：

• converter - 格式转换工具
• developer - 开发者工具
• text - 文本处理工具
• image - 图片处理工具
• utility - 实用工具

🌿 组织架构

JustHTMLs 采用 GitHub 组织进行管理：

• justhtmls/html-tools - 主网站仓库
• justhtmls/tools - 工具集合仓库（可选）
• justhtmls/docs - 文档仓库（可选）

🔄 工作流程

工具提交流程：

1. 开发者按规范创建工具文件夹和文件
2. 通过 GitHub Issues 提交工具到 justhtmls/html-tools
3. 维护者审核工具代码和功能
4. 审核通过后，维护者将工具合并到主仓库
5. 更新 index.json 索引文件
6. 工具上线到 JustHTMLs 网站

🐛 报告问题

如果你发现了 Bug 或有改进建议：

• 使用 GitHub Issues 报告问题
• 提供详细的复现步骤
• 附上截图或错误信息

❤️ 致谢

感谢所有贡献者！你的贡献让 JustHTMLs 变得更加完善。