Skip to content

Document macdoc HTML to PDF route #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kiki830621 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document macdoc HTML to PDF route #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions plugins/macdoc/.codex-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "macdoc",
"version": "1.1.0",
"description": "macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理",
"version": "1.1.1",
"description": "macOS 原生文件處理 CLI — 格式轉換（含 HTML→PDF via playwright）、VLM OCR（含 host profile 設定）、SRT 處理",
"author": {
"name": "Che Cheng"
},
Expand All @@ -11,8 +11,8 @@
"repository": "https://github.com/PsychQuant/psychquant-codex-plugins",
"interface": {
"displayName": "macdoc",
"shortDescription": "macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理",
"longDescription": "macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理",
"shortDescription": "macOS 原生文件處理 CLI — 格式轉換（含 HTML→PDF via playwright）、VLM OCR（含 host profile 設定）、SRT 處理",
"longDescription": "macOS 原生文件處理 CLI — 格式轉換（含 HTML→PDF via playwright）、VLM OCR（含 host profile 設定）、SRT 處理",
"developerName": "Che Cheng",
"category": "productivity",
"capabilities": [
Expand Down
36 changes: 27 additions & 9 deletions plugins/macdoc/skills/macdoc/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: macdoc
description: |
macOS 原生文件處理 CLI 工具的使用指南。
當需要做格式轉換（SRT→HTML、MD→HTML、DOCX→MD）、
當需要做格式轉換（SRT→HTML、MD→HTML、HTML→PDF、DOCX→MD）、
VLM OCR（PDF/圖片→文字）、或 SRT 逐字稿處理時使用。
觸發詞：「macdoc」「轉換格式」「OCR」「逐字稿轉HTML」
「手寫筆記辨識」「PDF轉文字」
Expand All @@ -17,7 +17,7 @@ description: |

| 子命令 | 用途 | 常用場景 |
|--------|------|---------|
| `convert` | 格式轉換 | SRT→HTML、MD→HTML、DOCX→MD |
| `convert` | 格式轉換 | SRT→HTML、MD→HTML、HTML→PDF、DOCX→MD |
| `ocr` | VLM OCR | PDF/圖片→文字（手寫筆記辨識） |
| `config` | 設定管理 | AI CLI 工具、OCR host/model 預設值 |
| `pdf` | PDF→LaTeX | 學術 PDF 處理（較少用） |
Expand All @@ -33,13 +33,14 @@ macdoc convert --to <format> [options] <input>

### 支援格式

| --to | 說明 | 範例 |
|------|------|------|
| `html` | 轉 HTML | SRT→逐字稿網頁、MD→講義網頁 |
| `md` | 轉 Markdown | DOCX→MD |
| `docx` | 轉 Word | MD→DOCX |
| `pdf` | 轉 PDF | MD→PDF（透過 textutil） |
| `json` | 轉 JSON | SRT→結構化 JSON |
| --to | 來源 | 說明 | Backend |
|------|------|------|---------|
| `html` | SRT, MD | 逐字稿網頁、講義網頁 | macdoc converters |
| `md` | DOCX | Word 轉 Markdown | word-to-md-swift |
| `docx` | MD | Markdown 轉 Word | md-to-word-swift |
| `pdf` | MD | 純文字/Markdown 轉 PDF | textutil |
| `pdf` | HTML/HTM | HTML（含 CSS、`@page`、分頁規則）轉 PDF，保留版面 | playwright Chromium |
| `json` | SRT | 逐字稿轉結構化 JSON | srt-to-html-swift |

### 常用選項

Expand All @@ -53,6 +54,14 @@ macdoc convert --to <format> [options] <input>
| `--frontmatter` | 包含 YAML frontmatter |
| `--html-extensions` | MD 中保留 `<u>/<sup>/<sub>/<mark>` |

### 前置需求

HTML→PDF 需要 Playwright CLI 與 Chromium：

```bash
pip install playwright && playwright install chromium
```

### 常用工作流

#### SRT → 可搜尋的逐字稿 HTML
Expand All @@ -75,6 +84,14 @@ macdoc convert --to html --full --output lecture.html notes.md

產出的是裸 HTML，需要手動替換 `<head>` 加入 CSS 連結和 lecture-header。

#### HTML → 保留排版 PDF

```bash
macdoc convert --to pdf styled-quote.html --output quote.pdf
```

這條路徑走 playwright Chromium，會保留 HTML/CSS、`@page`、`page-break-*`、grid 等版面規則；不要改用 `textutil`。

#### DOCX → Markdown

```bash
Expand Down Expand Up @@ -231,5 +248,6 @@ macdoc config ocr list

## 版本紀錄

- **1.1.1**：補上 HTML→PDF via playwright Chromium 文件；支援完整 CSS、`@page` 與分頁規則的保留排版 PDF 工作流
- **1.1.0**：新增 `config ocr` 子命令組,支援具名 host profile(`--host kyle` 等),預設 host/model 可存 config
- **1.0.0**：初版