# md2pdf

**Repository Path**: stonePlum/md2pdf

## Basic Information

- **Project Name**: md2pdf
- **Description**: md2pdf
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zhuchao文档转换系统安装指南
## 系统要求
- Ubuntu 24.04 LTS
- Python 3.8+
- 网络连接（安装依赖需要）
## 安装步骤
### 1. 系统初始化
```bash
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装基础工具
sudo apt install -y curl wget git unzip
# 安装 Python 3.8+（Ubuntu 24 默认已安装）
python3 --version  # 确认版本 >= 3.8
```
### 2. 安装 pipx（Python 包管理器）
```bash
# 安装 pipx
sudo apt install -y pipx
pipx ensurepath
# 验证安装
pipx --version
```
### 3. 安装 md2pdf-mermaid 及依赖
```bash
# 安装 md2pdf-mermaid
pipx install md2pdf-mermaid
# 安装 Chromium 浏览器（Mermaid 渲染必需）
pipx run playwright install chromium
# 验证安装
md2pdf --version
```
### 4. 安装 pymupdf（PDF 书签注入）
```bash
# 安装 pymupdf
pipx install pymupdf
# 验证安装
~/.local/share/pipx/venvs/pymupdf/bin/python3 -c "import fitz; print('pymupdf OK')"
```
### 5. 安装文档转换脚本
```bash
# 创建脚本目录
mkdir -p ~/.local/bin
# 下载转换脚本,放入当前目录脚本
vim ~/.local/bin/mdpub 
vim ~/.local/bin/mdpub_html.py 
# 添加执行权限
chmod +x ~/.local/bin/mdpub
# 添加到 PATH（如果 ~/.local/bin 不在 PATH 中）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 验证脚本
mdpub --help
```
### 6. 配置环境变量
```bash
# 确保脚本路径在 PATH 中
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
## 使用方法
### 基本用法
```bash
# 转换 Markdown 到 PDF（带书签）+ HTML（带目录）
mdpub 文档.md -o 输出.pdf
# 自定义输出文件名
mdpub 文档.md -o 自定义名称.pdf
# 只生成 PDF，不生成 HTML
mdpub 文档.md -o 输出.pdf --no-html
# 查看帮助
mdpub --help
```
### 功能特性
1. **Mermaid 图表渲染**：自动将 Mermaid 代码转换为高质量图片
2. **PDF 书签**：自动生成章节书签
3. **HTML 侧边栏目录**：可折叠的目录导航
4. **正文内目录**：Word 风格的目录
5. **图片放大**：点击图片可放大查看
6. **响应式设计**：适配手机和桌面
## 常见问题
### 1. Playwright 浏览器安装失败
```bash
# 重新安装 Chromium
pipx run playwright install chromium
```
### 2. 权限问题
```bash
# 确保脚本有执行权限
chmod +x ~/.local/bin/mdpub
# 检查 PATH
echo $PATH | grep ".local/bin"
```
### 3. 依赖缺失
```bash
# 重新安装所有依赖
pipx reinstall md2pdf-mermaid
pipx reinstall pymupdf
```
## 卸载方法
```bash
# 卸载 md2pdf-mermaid
pipx uninstall md2pdf-mermaid
# 卸载 pymupdf
pipx uninstall pymupdf
# 删除脚本
rm -f ~/.local/bin/mdpub ~/.local/bin/mdpub_html.py
# 移除 PATH 配置（可选）
sed -i '/export PATH="$HOME\/.local\/bin:$PATH"/d' ~/.bashrc
```
## 注意事项
1. **虚拟环境**：建议在虚拟环境中使用，避免系统 Python 冲突
2. **网络连接**：安装 Chromium 需要网络连接
3. **磁盘空间**：Chromium 浏览器约 250MB
4. **权限**：确保对 ~/.local 目录有写入权限
## 示例
```bash
# 转换示例文档
mdpub 用户手册.md -o 住潮生活用户手册.pdf
# 查看生成的文件
ls -la 住潮生活用户手册*
```
安装完成后，即可使用 `mdpub` 命令将 Markdown 文档转换为带书签的 PDF 和带目录的 HTML 文件。