Jacopo Mauro 个人网站镜像文档

1. 镜像概述和主要用途

1.1 概述

本镜像用于构建和运行 Jacopo Mauro 的个人网站，基于 wowchemy/starter-academic 主题，使用 Hugo 静态网站生成器构建。

1.2 主要用途

• 本地开发与调试个人网站
• 生成静态网站文件
• 管理学术出版物（通过 academic-admin 工具）

2. 核心功能和特性

• 主题集成：基于 wowchemy/starter-academic 学术主题，支持个人简历、出版物、项目等内容展示
• Hugo 构建：使用 klakegg/hugo:ext-debian-ci 镜像作为基础，支持 Hugo 扩展功能
• 本地开发支持：提供端口映射和目录挂载，实现本地源码实时更新与预览
• Shell 环境：支持进入容器 Shell，便于执行复杂命令和调试
• 学术工具集成：集成 academic-admin 工具，支持从 BibTeX 文件导入学术出版物

3. 使用场景和适用范围

3.1 适用场景

• 个人网站本地开发与调试
• 学术出版物信息批量导入与管理
• 静态网站生成前的本地测试
• 网站主题定制与功能扩展开发

3.2 适用范围

• 开发者（需具备基本 Docker 和 Hugo 使用经验）
• 学术工作者（需管理个人学术出版物）

4. 详细使用方法和配置说明

4.1 前提条件

• 已安装 Docker
• 本地已克隆网站源码（或当前目录为网站源码根目录）
• 若使用 academic-admin，需安装 Python 3 和 pip3

4.2 本地运行网站

通过以下命令启动本地服务器，实时预览网站：

docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:ext-debian-ci hugo server

参数说明：

• --rm：容器退出后自动删除
• -it：交互式终端
• -v $(pwd):/src：将当前目录（网站源码）挂载到容器内 /src 目录
• -p 1313:1313：映射容器内 1313 端口到本地 1313 端口（Hugo 默认端口）
• klakegg/hugo:ext-debian-ci：基础 Hugo 镜像（带扩展功能的 Debian CI 版本）
• hugo server：启动 Hugo 开发服务器，支持实时热重载

4.3 获取容器 Shell 环境

如需执行复杂命令（如文件操作、依赖安装），可进入容器 Shell：

docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:ext-debian-ci /bin/bash

进入后，工作目录默认为 /src（即本地挂载的网站源码目录）。

4.4 学术出版物导入与管理

4.4.1 安装 academic-admin 工具

在本地环境（非容器内）执行以下命令安装：

pip3 install -U academic

4.4.2 导入 BibTeX 出版物

1. 进入网站源码目录：

   cd <MY_WEBSITE_FOLDER>  # 替换为实际网站源码目录路径
   

2. 执行导入命令：

   academic import --bibtex mybib.bib --normalize
   

   • --bibtex mybib.bib：指定 BibTeX 格式的出版物文件路径（需替换为实际文件）
   • --normalize：标准化导入的出版物数据格式

4.5 清理多余会议记录

导入出版物后，需运行清理脚本移除多余的会议记录：

/my_scripts/remove_proceedings.sh

注意：脚本路径 /my_scripts/remove_proceedings.sh 为容器内路径，需确保该脚本存在于网站源码的 my_scripts 目录下（通过 -v 挂载到容器内）。

5. 配置说明

5.1 目录挂载

• 必须将本地网站源码目录挂载到容器 /src 目录，确保 Hugo 能读取源码并生成网站：

  -v $(pwd):/src  # $(pwd) 为当前终端所在目录，需确保是网站源码根目录
  

5.2 端口映射

• 默认使用 1313 端口（Hugo 标准端口），如需修改本地端口，可调整 -p 参数：

  -p <本地端口>:1313  # 例如：-p 8080:1313（本地通过 8080 端口访问）
  

5.3 academic-admin 配置

• 导入时需确保 BibTeX 文件路径正确，支持相对路径（相对于网站源码目录）
• --normalize 参数可选，用于统一出版物字段格式（如作者名、期刊名）

6. 部署方案示例

6.1 本地开发启动命令

# 克隆网站源码（首次使用）
git clone [***] my-website && cd my-website

# 启动本地预览服务器
docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:ext-debian-ci hugo server

6.2 生成静态网站文件

# 在容器内执行 Hugo 构建命令，生成静态文件到 public 目录
docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-debian-ci hugo

生成的静态文件位于本地源码目录的 public 文件夹，可直接部署到 Nginx、Netlify 等静态托管服务。