开发指南

相关源文件

• CLA-entity.md
• CLA-individual.md
• LICENSE
• Makefile
• contributors/adam-p.md
• src/_locales/fr/description.txt
• src/_locales/fr/markdown-here-image2.txt
• src/_locales/fr/md-for-screenshot.md.txt
• src/_locales/ru/description.txt
• src/_locales/zh_CN/description.txt
• src/_locales/zh_CN/markdown-here-image2.txt
• src/_locales/zh_CN/md-for-screenshot.md.txt
• src/_locales/zh_CN/screenshot-captions.txt

本文档为希望为 Markdown Here 项目做出贡献的开发者提供了全面的指导。它涵盖了环境设置、构建过程、测试程序和贡献指南。有关整体系统架构的信息，请参阅核心架构；有关扩展结构详情，请参阅扩展结构。

设置开发环境

在为 Markdown Here 贡献代码之前，您需要设置本地开发环境。

先决条件

• Git
• Node.js (含 npm)
• 用于测试的浏览器（Chrome、Firefox、Thunderbird 等）

快速入门

1. 克隆仓库:

   git clone https://github.com/adam-p/markdown-here.git
   cd markdown-here
   

2. 安装依赖：项目使用 npm 管理依赖。运行

   npm install
   

3. 配置您的浏览器进行测试:

   • Chrome：导航到 chrome://extensions/，启用“开发者模式”，然后使用“加载已解压的扩展程序”从您的本地 src 目录加载扩展程序。
   • Firefox：导航到 about:debugging，点击“此 Firefox”，然后点击“加载临时附加组件”，并选择您本地 src 目录中的任意文件。
   • Thunderbird：遵循 Firefox 的说明，但在 Thunderbird 中使用“附加组件管理器”。

来源：Makefile，README.md

项目结构

Markdown Here 代码库的组织方式旨在支持多种浏览器平台，同时共享核心功能。

• src/common/：包含所有平台共享的核心功能
• src/chrome/：Chrome 专用的扩展程序文件
• src/firefox/：Firefox 专用的扩展程序文件
• src/thunderbird/：Thunderbird 专用的扩展程序文件
• src/_locales/：国际化文件
• utils/：构建和开发实用工具
• test/：测试文件

来源：系统架构图

构建系统

Markdown Here 使用构建脚本为不同平台打包扩展程序。

构建扩展程序

为所有平台构建扩展程序

make build

此命令将

1. 清理 dist/ 目录
2. 运行 utils/build.js 中的构建脚本
3. 在 dist/ 目录中为 Chrome、Firefox 和 Thunderbird 创建扩展程序包

或者，您可以使用 npm

npm run build

来源：Makefile:12-14

测试

在向 Markdown Here 提交更改之前，测试至关重要。有几种方法可以测试您的更改

手动测试

1. 使用 make build 构建扩展程序
2. 将扩展程序加载到您的浏览器中
   • 对于 Chrome：从 src/ 加载已解压的扩展程序
   • 对于 Firefox/Thunderbird：从 dist/ 安装 .xpi 文件
3. 测试受您更改影响的所有功能
4. 跨不同电子邮件客户端（Gmail、Outlook、Yahoo 等）进行测试

测试功能

测试时，请确保涵盖以下内容

1. 基本的 Markdown 渲染
2. 代码语法高亮
3. 数学公式渲染（如果适用）
4. 选项页面功能
5. 国际化（如果修改字符串）

来源：系统架构图

贡献指南

欢迎并鼓励为 Markdown Here 做出贡献。请遵循以下步骤进行贡献

拉取请求流程

1. 派生仓库并创建功能分支
2. 进行更改并遵循项目的代码风格
3. 在不同平台进行全面测试
4. 提交拉取请求，并附上清晰的更改描述
5. 签署贡献者许可协议（详情见下文）

代码风格指南

• 遵循项目中现有的代码风格
• 使用有意义的变量名和函数名
• 为复杂逻辑添加注释
• 必要时更新文档

来源：CLA-individual.md，CLA-entity.md

法律要求

贡献者许可协议

所有贡献者在接受其贡献之前，都必须签署贡献者许可协议 (CLA)

1. 对于个人：CLA-individual.md
2. 对于实体：CLA-entity.md

签署 CLA

1. 阅读相应的 CLA 文档
2. 在 /contributors 目录中创建一个以您的 GitHub 用户名命名的文件（例如，contributors/username.md）
3. 包含 CLA 协议文本和您的签名（参见contributors/adam-p.md 作为示例）
4. 将此文件作为您的拉取请求的一部分提交

许可证

Markdown Here 在 MIT 许可下获得授权。所有贡献都将在此许可下涵盖。

来源：LICENSE，contributors/adam-p.md，CLA-individual.md，CLA-entity.md

开发工作流

下图说明了 Markdown Here 典型的开发工作流程

此工作流程确保所有贡献在合并到主代码库之前都经过充分测试和审查。

来源：CLA-individual.md，Makefile

国际化开发

在处理国际化 (i18n) 功能时，请遵循以下指南

添加或修改翻译

1. 在 src/_locales/ 中找到相应的语言文件
2. 按照现有格式编辑或添加翻译
3. 通过在浏览器中设置目标语言来构建和加载扩展程序，从而测试更改

添加新语言

1. 在 src/_locales/ 中创建一个包含相应语言代码的新目录
2. 从英文 (en) 目录复制模板文件
3. 翻译复制文件中的所有字符串
4. 通过构建和加载扩展程序来测试新语言

来源：src/_locales/fr/description.txt，src/_locales/zh_CN/description.txt，src/_locales/ru/description.txt

常见开发任务

任务	命令	描述
构建所有扩展程序	make build	为所有平台创建扩展程序包
清理构建产物	make clean	删除 dist/ 目录
完全重建	make all	结合清理和构建
开发构建	从 src/ 加载已解压的扩展程序	用于开发期间更快的测试

来源：Makefile

故障排除

问题	解决方案
构建失败	检查 Node.js 版本，更新依赖
扩展程序无法加载	检查浏览器控制台是否存在错误
更改未显示	确保在浏览器中重新加载扩展程序
CLA 验证问题	确保您的 CLA 文件遵循确切的格式

遵循本开发指南，您将能够有效地为 Markdown Here 项目做出贡献。如果您遇到本文未涵盖的任何问题，请在 GitHub 仓库中提出一个 issue。