repo2pdf

NPM：https://www.npmjs.com/package/repo2pdf

网站：https://repo2pdf.vercel.app/

repo2pdf 是一款创新多功能工具，旨在将 GitHub 仓库无缝转换为格式良好、视觉吸引且易于导航的 PDF 文件。通过自动化克隆仓库和解析代码文件的过程，repo2pdf 可服务于多种用途，包括教学、代码审查、离线参考、归档、AI 训练和文档嵌入。该工具的灵活性拓展了与代码库交互的视野，弥合了动态编码世界与静态、普遍可访问的 PDF 格式之间的差距，满足了多样化的用户需求和创新应用。

• repo2pdf
  • 安装和使用
    • 使用 NPX 安装和使用 repo2pdf
    • 通过克隆仓库安装和使用 repo2pdf
  • 配置
    • 文件结构示例
  • 故障排除 / 常见问题
  • 为 repo2pdf 做贡献
    • 报告错误
    • 提出改进建议
    • 编写代码
    • 认识我们的贡献者
  • 项目结构
  • 许可证
  • Star 历史

---

安装和使用

repo2pdf 可以通过直接使用 NPX 或从 GitHub 克隆仓库来安装。根据所选方法，步骤和提示会有所不同。

新功能！在这里使用网页应用

---

使用 NPX 安装和使用 repo2pdf

此方法从 NPM 注册表下载并安装最新版本的 repo2pdf。

1. 使用 NPX 安装 repo2pdf：

npx repo2pdf

2. 脚本将开始运行。按照提示提供必要的信息。
   • GitHub 仓库 URL
   • 输出文件名
   • 是否保留克隆的仓库（是/否）

---

通过克隆仓库安装和使用 repo2pdf

此方法涉及手动克隆 repo2pdf 仓库并在本地机器上设置。

1. 克隆仓库：

git clone https://github.com/BankkRoll/repo2pdf

2. 进入 repo2pdf 目录：

cd repo2pdf

3. 安装依赖：

npm install

4. 构建脚本：

npm run build

5. 运行脚本：

npm start

6. 脚本将开始运行。按照提示提供必要的信息：
   • 是否克隆仓库或使用本地仓库
     • 如果使用本地仓库，提供路径
     • 如果克隆仓库，提供 URL
   • 功能清单，选择是否：
     • 在 PDF 中添加行号
     • 在 PDF 中添加页码
     • 在 PDF 中添加高亮
     • 从代码中删除注释
     • 从代码中删除空行
     • 生成一个 PDF 文件还是每个文件一个 PDF
   • 输出 PDF 文件名或输出目录
   • 生成 PDF 后是否保留克隆的仓库

请注意，您需要在系统上安装 Node > 18 和 git（对于非本地仓库）才能运行 repo2pdf。

---

配置

repo2pdf 自动忽略某些文件类型和目录（例如 .png、.git）。 要自定义要忽略的文件和目录，您可以在仓库根目录添加一个 repo2pdf.ignore 文件。

请注意，如果您使用本地仓库，repo2pdf.ignore 文件必须位于仓库目录的根目录。您可能需要在忽略列表中添加更多目录，因为脚本不会自动忽略不同的构建文件和目录。

文件结构示例

{
  "ignoredFiles": ["tsconfig.json", "dist", "node_modules"],
  "ignoredExtensions": [".raw"]
}

---

故障排除 / 常见问题

<details> <summary>问：我遇到了"Failed to install [package-name]"错误。我应该怎么做？</summary> 答：确保您的系统上安装了 Node.js 和 npm。尝试运行以下命令手动安装所需的包：

npm install [package-name]

</details> <details> <summary>问：如何自定义生成的 PDF 的样式？</summary> 答：您可以修改 `clone.ts` 或 `syntax.ts` 中的代码来更改 PDF 文档的字体、字体大小、颜色和其他样式选项。

// 示例：在 syntax.ts 中更改字体大小
doc.fontSize(12);

</details> <details> <summary>问：支持哪些类型的文件转换为 PDF？</summary> 答：目前，repo2pdf 支持所有基于文本的文件转换为 PDF。二进制文件如图像或编译的二进制文件会被忽略。 </details> <details> <summary>问：如何修改被忽略的文件列表？</summary> 答：您可以在仓库根目录添加一个 `repo2pdf.ignore` 文件来自定义被忽略的文件列表。以下是该文件的结构示例：

{
  "ignoredFiles": ["tsconfig.json"],
  "ignoredExtensions": [".md"]
}

</details> <details> <summary>问：如何在生成的 PDF 中包含行号？</summary> 答：在脚本执行过程中，您会被问到"Include line numbers?"（包含行号？）。回答"Y"将在生成的 PDF 中包含行号。 </details> <details> <summary>问：如何在生成 PDF 后保留克隆的仓库？</summary> 答：在脚本执行过程中，您会被问到"Keep cloned repository?"（保留克隆的仓库？）。回答"Y"将在生成 PDF 后保留系统上克隆的仓库。 </details> <details> <summary>问：如何为本地仓库生成 PDF？</summary> 答：运行脚本时，系统会询问您是要克隆仓库还是使用本地仓库。选择后者并提供本地仓库路径即可。 </details>

---

为 repo2pdf 做贡献

**您的见解、技能和宝贵时间可以为 repo2pdf 的发展做出巨大贡献！**我们始终很高兴看到社区参与塑造这个工具，使其更加高效和功能丰富。

报告错误

遇到问题了吗？我们随时为您提供帮助！请：

1. 在 GitHub 上开一个 issue 详细说明错误。
2. 深入描述问题。分享重现问题的步骤和您收到的任何错误信息。
3. 如果可能，提供您的操作系统和 Node.js 版本信息。

提出改进建议

有关于新功能或改进现有功能的好主意吗？我们洗耳恭听！请：

1. 在 GitHub 上开一个 issue 分享您的建议。
2. 尽可能详细地解释您想要实现什么以及为什么它对项目有益。

编写代码

如果您准备好亲自动手贡献代码以修复错误或实现新功能，以下是您可以开始的方法：

1. Fork 仓库。
2. 为您的更改创建一个新分支。
3. 在您的分支中进行更改。
4. 从您的分支向主 repo2pdf 仓库提交拉取请求。

在您的拉取请求中，请清楚地描述您所做的更改。我们感谢符合我们编码规范并与现有代码库保持一致的贡献 - 这有助于我们维护项目质量并提高审核过程的效率。

以下是一些可以在 repo2pdf 中实施的功能创意和改进，以增强其功能和用户体验：

• **目录生成：**根据目录自动生成章节，根据文件生成小节。
• **可自定义主题：**允许自定义生成 PDF 的字体、颜色和布局。
• **交互式进度条：**在转换过程中在终端显示实时进度条。
• **支持私有仓库：**实现 OAuth2 GitHub 认证以支持私有仓库。
• **增强错误处理：**当无法克隆仓库时提供清晰的错误信息。
• **转换选项预设：**定义预设，如"极简"：无行号、无高亮；"全功能"：有行号、有语法高亮。
• **支持更多版本控制系统：**扩展支持其他版本控制系统，如 GitLab、Bitbucket 等。
• **支持非 Git 仓库：**添加对其他版本控制系统（如 Mercurial 或 SVN）的支持。
• **客户端网页应用：**开发一个用户友好的网页应用，用于转换仓库和自定义设置。
• **文本压缩：**使用字体子集化和压缩技术减小生成的 PDF 大小。

欢迎通过实现这些想法或提出新的想法来为项目做出贡献！

---

认识我们的贡献者

我们非常感谢社区的宝贵贡献。认识一下帮助塑造 repo2pdf 的人们：

---

许可证

repo2pdf 是开源软件，根据 MIT 许可证授权。有关更多信息，请参阅 LICENSE 文件。

星标历史

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=BankkRoll/repo2pdf&type=Date&theme=dark"> <img alt="星标历史图表" src="https://api.star-history.com/svg?repos=BankkRoll/repo2pdf&type=Date"> </picture>