9.6 KiB

Raw Permalink Blame History

my-rendercv

個人履歷配置專案，使用 RenderCV 從 YAML 檔案生成 PDF 履歷。

專案結構

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

環境安裝

需求：Python 3.12 或以上版本

pip install "rendercv[full]"

其他安裝方式：

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

# uv
uv tool install "rendercv[full]"

驗證安裝：

rendercv --version

快速開始

生成履歷（全格式）

rendercv render my_cv.yaml

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

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

rendercv render my_cv.yaml --watch

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

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

指定輸出路徑

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

YAML 配置結構說明

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

`cv` — 履歷內容

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

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 模板（可自訂欄位排列）

目前使用的主色系：

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

`locale` — 語言本地化

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

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

`settings` — 生成設定

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

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

客製化設計

修改主題色

編輯 design.colors 區塊：

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

修改條目模板

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

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 等。

建立自訂主題

rendercv create-theme my-theme

產生 my-theme/ 資料夾，包含 Typst 模板，可直接修改樣式後，在 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 目錄中

配置修改如下

  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 但是一直無法生效！目前推測可能是字型版本需要基於 makeotfexe 2.6.0
使用 Source Han Serif | 思源宋体必須改叫 思源宋體 而不是 Source Han Serif TC
建議從 Google 下載字體 LXGW 這是一款系列源自 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：

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 是否有破壞性變更。

9.6 KiB Raw Permalink Blame History Unescape Escape