honkit 使用教程及部署github page

1. 什么是 Honkit？

Honkit 是一个现代化的静态书籍生成工具，它是基于旧版 GitBook 开发的，支持 Markdown 文件的编写和多种输出格式，如 HTML 和 PDF。

2. 初始化 Honkit 项目

2.1 创建 Honkit 项目

创建项目目录：

mkdir my-honkit-project
cd my-honkit-project

初始化 Honkit 项目：
```
npx honkit init
```
这会生成以下两个文件：
- README.md：书籍的主页面。
- SUMMARY.md：目录结构的定义。
安装 Honkit：
```
npm install honkit --save-dev
```

3. 本地构建书籍

3.1 运行开发服务器

在项目目录中运行以下命令启动本地预览：

npx honkit serve

默认情况下，书籍会在 http://localhost:4000 上运行。

3.2 生成静态文件

当书籍准备好后，运行以下命令生成静态 HTML 文件：

npx honkit build

生成的文件会存储在 _book 目录中。

4. 生成 PDF 文件

Honkit 支持将书籍生成 PDF 文件，但需要预先安装 Calibre 电子书管理软件。

4.1 安装 Calibre

下载 Calibre：
- 访问 Calibre 官网：https://calibre-ebook.com/download。
- 下载并安装适合您系统的版本。
确保 Calibre 路径正确：
- 检查环境变量：
  - 通常，Calibre 安装会自动将路径添加到系统的环境变量 PATH 中。
  - 如果未自动添加，手动将 Calibre 的安装目录路径添加到 PATH 环境变量中。
- 例如，Windows 系统下，路径可能为：
```
C:\Program Files\Calibre2
```
- Linux 和 macOS 用户可通过以下命令验证：
```
which ebook-convert
```
  如果返回路径为空，说明需要手动添加。
重新打开终端：
添加路径后，确保关闭并重新打开终端。

4.2 生成 PDF

运行以下命令生成 PDF 文件：

npx honkit pdf . output.pdf

. 表示当前目录。
output.pdf 是生成的 PDF 文件名。

5. 部署到 GitHub Pages

5.1 创建 GitHub 仓库

前往 GitHub 创建一个新仓库（例如 my-honkit-book）。

将本地项目与远程仓库关联：

git init
git remote add origin https://github.com/<username>/my-honkit-book.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

5.2 配置 GitHub Actions 自动部署

创建 GitHub Actions 配置文件：
在项目的根目录下创建 .github/workflows/deploy.yml 文件，内容如下：

name: Deploy Honkit to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v3

    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install Dependencies
      run: npm install

    - name: Build Honkit
      run: npx honkit build

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./_book

提交配置文件：
提交并推送配置文件到 GitHub：

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions for deployment"
git push origin main

启用 GitHub Pages：
- 进入仓库的 Settings > Pages。
- 在 Source 下选择 gh-pages 分支，点击保存。

6. 绑定自定义域名

6.1 配置 GitHub Pages

进入仓库的 Settings > Pages。
在 Custom domain 中输入您的自定义域名（例如 www.example.com）。
点击 Save。GitHub 会自动生成一个 CNAME 文件。

6.2 配置 DNS 记录

登录您的域名注册商控制台，添加以下 DNS 记录：

绑定子域名（例如 www.example.com）：
添加 CNAME 记录：
```
www  CNAME  <username>.github.io
```

注意：将 <username> 替换为您的 GitHub 用户名。

6.3 启用 HTTPS

返回 GitHub 仓库的 Settings > Pages。
勾选 Enforce HTTPS，以启用 HTTPS 访问。

自定义域名每次推送后消失的解决方法

当每次推送代码后，自定义域名设置消失，通常是由于 CNAME 文件被覆盖或删除。GitHub Pages 需要根目录的 CNAME 文件来保存自定义域名信息。如果该文件丢失或被覆盖，GitHub 就无法识别您的自定义域名。

解决方法

手动将 CNAME 文件添加到源码目录

创建 CNAME 文件：
在项目根目录（如 main 分支）下创建一个 CNAME 文件，并在文件中输入您的自定义域名，例如：
```
www.example.com
```

提交更改：
提交并推送 CNAME 文件到远程仓库：

git add CNAME
git commit -m "Add CNAME file"
git push origin main

验证：
每次部署后，CNAME 文件会自动被包含在 gh-pages 分支中，不会被覆盖。

验证步骤

检查 CNAME 文件：
- 进入 GitHub 仓库的 gh-pages 分支，确认根目录下有 CNAME 文件。
- 文件内容应为您的自定义域名，例如：
```
www.example.com
```
检查 GitHub Pages 设置：
- 转到 Settings > Pages。
- 确认自定义域名已正确显示，并启用 HTTPS。
测试访问：
使用您的自定义域名访问页面，确认是否能够正确加载。

7. 常见问题及解决方法

问题 1：`npx honkit pdf` 报错 `Command failed: ebook-convert not found`

原因：
Calibre 未正确安装，或 ebook-convert 工具未添加到系统的 PATH 环境变量中。

解决方法：

确保 Calibre 已安装，并重新确认安装路径：
- Windows 默认路径：C:\Program Files\Calibre2。
- macOS/Linux 使用 which ebook-convert 检查路径。
手动将 Calibre 的安装路径添加到系统环境变量中：
- Windows：
  - 打开“环境变量”设置，找到 PATH。
  - 添加 C:\Program Files\Calibre2。
- Linux/macOS：
  - 编辑 ~/.bashrc 或 ~/.zshrc 文件，添加以下内容：
```
export PATH="/path/to/calibre:$PATH"
```
    替换 /path/to/calibre 为 Calibre 的实际路径。
  - 保存后运行 source ~/.bashrc 或 source ~/.zshrc 使更改生效。
重新运行 npx honkit pdf。

问题 2：GitHub Actions 部署失败，提示 `Permission denied`

原因：
GitHub Actions 无法向 gh-pages 分支推送更改，通常是因为缺少权限。

解决方法：

确保 GitHub 仓库的 Settings > Actions > General 中已启用 Read and write permissions：
- 打开 Workflow permissions，选择 Read and write permissions。
- 勾选 Allow GitHub Actions to create and approve pull requests。
确认 GitHub Actions 配置文件中使用的是 github_token：
```
with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
```

问题 3：GitHub Pages 部署成功，但自定义域名未生效

原因：
DNS 记录配置错误或未生效。

解决方法：

登录域名管理平台，检查 DNS 配置：
- 确认 A 记录或 CNAME 记录配置正确。
- 等待 DNS 记录生效（可能需要 5-48 小时）。
检查仓库根目录下是否有 CNAME 文件，内容是否正确（应与自定义域名一致）。
验证 DNS 配置是否正确：
- 使用 DNS Checker 验证域名解析。
启用 HTTPS：
- 进入 Settings > Pages，勾选 Enforce HTTPS。

问题 4：生成的书籍内容显示错乱或样式缺失

原因：

Markdown 文件中格式不正确。
SUMMARY.md 的目录结构未正确链接。

解决方法：

确认 Markdown 文件的格式是否符合规范。
检查 SUMMARY.md 中的链接是否与文件路径一致：
```
* [章节标题](path/to/file.md)
```
清理并重新构建书籍：
```
npx honkit build
```

问题 5：自定义 PDF 样式未生效

原因：
未指定自定义样式文件或样式文件路径错误。

解决方法：

创建一个 CSS 样式文件（如 custom.css），自定义 PDF 的排版样式。
使用以下命令生成 PDF 并指定样式文件：
```
npx honkit pdf --css custom.css . output.pdf
```
8. 支持与反馈

如果您遇到未列出的问题或有其他疑问，请参考以下支持途径：

Honkit 官方文档：https://honkit.netlify.app
GitHub 仓库：https://github.com/honkit/honkit
社区支持：搜索相关问题或发帖提问。

完成这些步骤后，您可以成功使用 Honkit 创建、部署和管理文档，解决常见问题，并生成符合您需求的 HTML 和 PDF 文档！

标签：无

1. 什么是 Honkit？

2. 初始化 Honkit 项目

2.1 创建 Honkit 项目

3. 本地构建书籍

3.1 运行开发服务器

3.2 生成静态文件

4. 生成 PDF 文件

4.1 安装 Calibre

4.2 生成 PDF

5. 部署到 GitHub Pages

5.1 创建 GitHub 仓库

5.2 配置 GitHub Actions 自动部署

6. 绑定自定义域名

6.1 配置 GitHub Pages

6.2 配置 DNS 记录

6.3 启用 HTTPS

自定义域名每次推送后消失的解决方法

解决方法

验证步骤

7. 常见问题及解决方法

问题 1：npx honkit pdf 报错 Command failed: ebook-convert not found

问题 2：GitHub Actions 部署失败，提示 Permission denied

问题 3：GitHub Pages 部署成功，但自定义域名未生效

问题 4：生成的书籍内容显示错乱或样式缺失

问题 5：自定义 PDF 样式未生效

8. 支持与反馈

你的评论

问题 1：`npx honkit pdf` 报错 `Command failed: ebook-convert not found`

问题 2：GitHub Actions 部署失败，提示 `Permission denied`