My Local Overleaf（本地 Overleaf 替代方案）

用 VS Code + Makefile + Git + Docker（可选） 在 macOS 上实现「像 Overleaf 一样开箱即用」的 LaTeX 写作体验：

• ✅ 从 Overleaf 下载的 .zip 一键导入即开工
• ✅ 本地 make pdf / make watch 编译 + VS Code PDF 预览自动刷新
• ✅ make docker-pdf 统一环境编译（解决“你能编译我不能”的问题）
• ✅ tex-autofix 自动从编译日志推断缺失 TeX 包并生成 requirements-texlive.txt（可选自动安装）
• ✅ GitHub/GitLab/Gitea 远端仓库持久化备份
• ✅ VS Code Live Share 多人实时协作（像 Overleaf 一样多人同时写）

本仓库提供的是工具脚本 + 使用指南。你导入的每个 LaTeX 项目就是一个独立仓库/工作目录。

---

目录结构

• scripts/latex-import-zip：导入 .zip -> 自动补齐 .vscode/、Makefile、.gitignore，并初始化 git
• scripts/tex-autofix：扫描 latexmk 日志，生成/安装缺失 tlmgr 包清单
• scripts/latex-enable-docker-repo：把任意项目改造成「repo 自带 Docker 编译规则」开箱即用（生成 build/latex.mk + Makefile）
• docs/USAGE.md：更详细的流程说明

---

环境准备（一次性）

1) 安装 BasicTeX + latexmk（macOS）

brew install --cask basictex
echo 'export PATH="/Library/TeX/texbin:$PATH"' >> ~/.zshrc
source ~/.zshrc

sudo tlmgr update --self
sudo tlmgr install latexmk

验证：

which latexmk
latexmk -v
pdflatex -version | head -n 1

2) 安装 VS Code 插件

• ✅ LaTeX Workshop（必须）
• （可选）GitLens
• （多人实时协作）Live Share

---

安装本仓库脚本（推荐）

把脚本放进 ~/bin，以后任何项目都能用（也符合你之前的 Homebrew/终端习惯）。

mkdir -p ~/bin
cp -f scripts/* ~/bin/
chmod +x ~/bin/*

# 确保 PATH 包含 ~/bin（如已设置可跳过）
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证：

which latex-import-zip
which tex-autofix
which latex-enable-docker-repo

---

快速开始：从 ZIP 导入并本地编译

1) 导入 zip（像 Overleaf 一样“打开就能写”）

latex-import-zip ~/Downloads/your_project.zip
cd your_project
code .

脚本会自动：

• 解压（并处理“zip 多一层目录”的常见情况）
• 生成 .vscode/settings.json（让 LaTeX Workshop 走 make pdf）
• 生成 .gitignore
• 生成 Makefile（统一入口）
• 初始化 git 并做一次初始提交（如果项目还不是 git repo）

2) 本地编译

make pdf
# 或持续编译
make watch

---

Docker 编译（统一环境）

适合：多人协作、不同机器环境不一致、或你想在 CI 里稳定编译。

方式 A：给项目“repo 内自带规则”（推荐）

在项目根目录运行：

latex-enable-docker-repo .

然后：

make docker-pdf

它会生成：

• build/latex.mk（repo 内规则）
• Makefile（优先 include build/latex.mk，没有才 fallback 到 ~/.config/latex/latex.mk）

方式 B：只用你本机全局规则（可选）

如果你已经配置了 ~/.config/latex/latex.mk（见 docs/USAGE.md），也可以不生成 build/latex.mk，直接 make docker-pdf。

---

自动补齐缺失 TeX 包：tex-autofix

当 latexmk 报错「缺包/缺字体」时：

tex-autofix --tex main.tex
# 生成 requirements-texlive.txt

想让它自动安装（需要 tlmgr 权限，必要时 sudo）：

tex-autofix --install --tex main.tex
# 或
sudo tex-autofix --install --tex main.tex

---

Git 远端仓库备份（持久化存储）

在 GitHub/GitLab/Gitea 创建一个空仓库后，在项目目录里：

git remote add origin <REMOTE_URL>
git push -u origin main

之后：

• 修改 -> git commit -> git push
• 协作者：git clone -> make pdf / make docker-pdf

---

Live Share 多人实时协作

• Host 启动：VS Code → Live Share → Start Collaboration Session
• Guest 加入链接后：Guest 的修改会实时写入 Host 的工作区文件（像 Host 自己敲键盘）
  但 Live Share 不会自动帮你 git commit/push —— 一般由 Host 会后统一提交。

推荐协作边界（黄金流程）：

会前：git pull
会中：Live Share 实时修改
会后：Host 统一 git commit + push

---

更多说明

详见：docs/USAGE.md