330 lines
9.6 KiB
Markdown
330 lines
9.6 KiB
Markdown
# 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
|