# my-rendercv

個人履歷配置專案，使用 [RenderCV](https://github.com/rendercv/rendercv) 從 YAML 檔案生成 PDF 履歷。

## 專案結構

```
my-rendercv/
├── my_cv.yaml        # 主要履歷配置檔（繁體中文）
├── photo.jpg             # 履歷照片
├── rendercv_output/      # 生成的輸出檔案（已 gitignore）
│   ├── *.pdf
│   ├── *.typ
│   ├── *.html
│   ├── *.md
│   └── *.png
└── README.md
```

## 環境安裝

**需求：Python 3.12 或以上版本**

```bash
pip install "rendercv[full]"
```

其他安裝方式：

```bash
# pipx（推薦，隔離全域工具）
pipx install "rendercv[full]"

# uv
uv tool install "rendercv[full]"
```

驗證安裝：

```bash
rendercv --version
```

---

## 快速開始

### 生成履歷（全格式）

```bash
rendercv render my_cv.yaml
```

輸出檔案會放在 `rendercv_output/` 目錄，包含 PDF、Typst 原始碼、HTML、Markdown、PNG。

### 監看模式（存檔後自動重新生成）

```bash
rendercv render my_cv.yaml --watch
```

### 只生成 PDF（跳過其他格式）

```bash
rendercv render my_cv.yaml --dont-generate-markdown --dont-generate-html --dont-generate-png
```

### 指定輸出路徑

```bash
rendercv render my_cv.yaml --pdf-path output/resume.pdf
```

---

## YAML 配置結構說明

配置檔分為四個頂層區塊：

### `cv` — 履歷內容

定義個人基本資訊與各章節內容。

```yaml
cv:
  name: "Ding-Lian Chen (陳定廉)"
  location: "Taipei, Taiwan"
  email: "shadow449515@gmail.com"
  phone: "(+886) 0979508405"
  social_networks:
    - network: GitHub
      username: Dingian

  sections:
    summary:
      - 純文字段落，直接放字串。

    skills:
      - bullet: 條列項目使用 bullet 欄位。

    experience:
      - company: 公司名稱
        position: 職稱
        location: 地點
        start_date: 2021-05
        end_date: present       # 目前在職用 present
        summary: 職位摘要
        highlights:
          - 重點項目 1
          - 重點項目 2

    projects:
      - name: 專案名稱
        position: 角色
        tech_stack: Python, FastAPI
        date: 2024-01 – Present
        link: https://example.com
        description: 專案描述
        highlights:
          - 重點項目

    education:
      - institution: 學校名稱
        area: 系所名稱
        degree: 學士
        start_date: 2011-08
        end_date: 2016-01
```

### `design` — 視覺設計

控制版面、顏色、字型、章節樣式等外觀設定。

| 區塊 | 說明 |
|------|------|
| `theme` | 主題（`classic`、`engineeringresumes`、`moderncv` 等） |
| `page` | 頁面尺寸、邊距、是否顯示頁尾 |
| `colors` | 各元素顏色（支援 `rgb(r, g, b)` 格式） |
| `typography` | 字型、字級、行距、對齊方式 |
| `header` | 標題區塊排版（照片位置、間距） |
| `section_titles` | 章節標題樣式（底線類型、粗細） |
| `entries` | 條目排版（欄寬、項目間距） |
| `templates` | 各條目的 Typst 模板（可自訂欄位排列） |

**目前使用的主色系：**

```yaml
colors:
  name: rgb(0, 79, 144)
  section_titles: rgb(0, 79, 144)
  links: rgb(0, 79, 144)
```

### `locale` — 語言本地化

控制日期格式、時間跨度文字等語言設定。

```yaml
locale:
  language: mandarin_chinese   # 中文格式
  # 可自訂以下文字（取消註解後修改）：
  # present: 至今
  # year: 年
  # months: 個月
  # month_abbreviations:
  #   - 1月
  #   ...
```

### `settings` — 生成設定

控制輸出行為與日期顯示。

```yaml
settings:
  current_date: '2026-01-02'     # 覆蓋頁尾的更新日期
  bold_keywords: []              # 自動加粗的關鍵字列表
  render_command:
    dont_generate_png: false
    dont_generate_markdown: false
```

---

## 客製化設計

### 修改主題色

編輯 `design.colors` 區塊：

```yaml
colors:
  name: rgb(180, 0, 0)
  section_titles: rgb(180, 0, 0)
  links: rgb(180, 0, 0)
```

### 修改條目模板

`design.templates` 可自訂各條目的欄位排列，使用預設變數（全大寫）：

```yaml
templates:
  experience_entry:
    main_column: |-
      **COMPANY**, POSITION
      SUMMARY
      HIGHLIGHTS
    date_and_location_column: |-
      LOCATION
      DATE
```

可用變數：`COMPANY`、`POSITION`、`SUMMARY`、`HIGHLIGHTS`、`DATE`、`LOCATION`、`NAME`、`DESCRIPTION`、`TECH_STACK`、`LINK` 等。

### 建立自訂主題

```bash
rendercv create-theme my-theme
```

產生 `my-theme/` 資料夾，包含 Typst 模板，可直接修改樣式後，在 YAML 中指定：

```yaml
design:
  theme: my-theme
```

### 修改字型
默認的字體支援對中文不友好，沒有加粗效果，所以需要手動替換字體進行渲染，此外 rendercv 版本必須高於2.8，否則無法生效

目前使用 https://github.com/notofonts/noto-cjk/releases 下載選擇 
- `Noto Serif CJK` 或 `Noto Sans CJK` 分別代表 思源宋体 和 思源黑体 (思源黑体于 2014 年 7 月首次发布，思源宋体于 2017 年 4 月发布)
- 語言選擇 `Language Specific OTFs Traditional Chinese — Taiwan (繁體中文—臺灣)` 

後放到 fonts 目錄中

配置修改如下
```yaml
  typography:
    font_family:
      body: Noto Serif CJK TC
      name: Noto Serif CJK TC
      headline: Noto Serif CJK TC
      connections: Noto Serif CJK TC
      section_titles: Noto Serif CJK TC
```
PS: 
- 嘗試使用 [SarasaGothic-TTF-1.0.37](https://github.com/be5invis/Sarasa-Gothic/releases/tag/v1.0.31) 但是一直無法生效！目前推測可能是字型版本需要基於 makeotfexe 2.6.0
- 使用 [Source Han Serif | 思源宋体](https://github.com/adobe-fonts/source-han-serif) 必須改叫 `思源宋體` 而不是 `Source Han Serif TC`
- 建議從 Google 下載字體 [LXGW](https://fonts.google.com/specimen/LXGW+WenKai+TC) 這是一款系列源自 https://github.com/lxgw/LxgwWenkai
- https://github.com/max32002/swei-spring 這個沒測試，但看起來應該也是可以使用

### 為什麼 Sarasa Gothic 無效，而 Noto Serif CJK 可以？

#### 1. 兩者核心差異

| 特性 | **Sarasa Gothic (更紗黑體)** | **Noto Serif CJK (思源宋體/明體)** |
| :--- | :--- | :--- |
| **字體分類** | **黑體 (Sans-serif)** | **宋體/明體 (Serif)** |
| **主要用途** | 程式碼編輯器、終端機 (Terminal) | 書籍排版、正式文件、學術論文 |
| **設計特色** | 混合「思源黑體」與「Iosevka」，強調**等寬 (Monospace)** | 傳統印刷風格，有明顯的筆畫裝飾（襯線） |
| **字體格式** | 多為 TTC (TrueType Collection) | OTF (OpenType Font) |

- **Sarasa Gothic** 的核心價值是解決「程式碼中，中英文寬度不匹配」的問題，強行將中文寬度設為英文的兩倍，非常適合寫程式。
- **Noto Serif CJK** 為長文閱讀設計，追求古典的印刷美感。

#### 2. 原因分析

**A. 襯線體 (Serif) 的預設配置**

`rendercv` 背後的核心引擎是 **XeLaTeX/LuaLaTeX**，預設的 CV 樣式通常要求**襯線體**（如 Times New Roman）。
- **Noto Serif CJK** 是標準的襯線體，能完美對接英文 Serif 字體。
- **Sarasa Gothic** 是黑體（無襯線），當樣式表要求 Serif 邏輯時，調用黑體可能導致字體族衝突或回退（Fallback）失敗。

**B. 字體格式與 LaTeX 的相容性**

`rendercv` 依賴的 `fontspec` 套件對 **OTF (OpenType)** 格式的支援最為穩定。
- **Noto Serif CJK** 提供標準 OTF 版本，其 CID-keyed 映射嚴謹，讓 LaTeX 引擎能精確定位「繁體中文」字形編碼。
- **Sarasa Gothic** 為實現等寬做了大量調整，內部字體元數據（Metadata）有時不符合傳統 LaTeX 引擎的預期，容易導致找不到字形或渲染空白。

**C. 等寬 (Monospace) 的干擾**

`rendercv` 生成 PDF 時會計算每個字符寬度以精確排版。
- **Sarasa Gothic** 是**等寬字體**，在非程式碼區域使用等寬字體，會導致字間距（Kerning）僵硬或跑版。
- **Noto Serif CJK** 是比例字體（Proportional），允許字符根據形狀有不同寬度，符合正式文件的排版邏輯。

#### 3. 總結建議

| 使用場景 | 推薦字體 |
| :--- | :--- |
| 寫程式或設定 Terminal | **Sarasa Gothic** |
| 用 RenderCV 生成正式履歷 | **Noto Serif CJK TC** 或 **Noto Sans CJK TC** |

如果在 Windows 上透過 `scoop` 安裝 Noto Serif：

```powershell
scoop install NotoSerifCJK-TC
```

安裝後，`rendercv` 就能透過字體名稱精確抓取，生成的 PDF 字形也會顯得更專業且符合傳統排版審美。

---

## 常用指令速查

| 指令 | 說明 |
|------|------|
| `rendercv render my_cv.yaml` | 生成全部格式 |
| `rendercv render my_cv.yaml --watch` | 監看模式，存檔自動重新生成 |
| `rendercv render my_cv.yaml --dont-generate-png --dont-generate-html` | 跳過 PNG 和 HTML |
| `rendercv render my_cv.yaml --pdf-path output.pdf` | 指定 PDF 輸出路徑 |
| `rendercv new "姓名"` | 建立新的範本 YAML |
| `rendercv create-theme 主題名` | 建立自訂 Typst 主題 |
| `rendercv --version` | 查看版本 |

---

## 注意事項

- `rendercv_output/` 已加入 `.gitignore`，不會提交生成的檔案。
- YAML 中可使用 Markdown 語法（`**粗體**`、`[連結](url)`），PDF 中可正常渲染。
- `settings.current_date` 會影響頁尾的更新日期顯示，需手動維護。
- 升級版本前建議確認 [Changelog](https://github.com/rendercv/rendercv/releases) 是否有破壞性變更。

## 引用内容

- https://github.com/wyh0626/resume-optimizer
- https://github.com/stepfun-ai/Step-3.5-Flash/blob/main/cookbooks/resume-analysis-agent-guide/resume_analyzer.py