Hugo小脚本：自动完善slug及image属性

Sun, 15 Feb 2026 17:47:11 +0800

重要

👍Gemini 3，脚本全是它写的！

主要功能

1. 自动生成 Slug

脚本会自动读取文章的 title：

如果标题是中文，它可以利用 deep-translator 自动将其翻译成英文，然后生成 Slug。
或者使用 --pinyin 参数将其转换为拼音 Slug。
它还会智能判断是否已经存在 Slug，避免覆盖手动设置好的内容。

2. 自动下载封面图

对于使用了 post-bundle 格式（即文件夹形式）的文章：

脚本会先检查目录中是否已经存在 cover.jpg、feature.jpg 等常见的封面文件。
如果没有，且 Front Matter 中的 image 字段为空，它会根据文章标题生成关键词，从 Picsum 下载一张高质量的随机图片作为封面。

3. 支持多语言

脚本考虑到了 Hugo 的多语言特性，如果在同一个文件夹下有 index.zh.md 和 index.en.md，它们会共享下载好的封面图，避免重复下载。

如何使用

安装依赖：

1

pip install python-frontmatter python-slugify deep-translator requests

运行脚本：

仅完善 Slug: python3 tools/front_matter.py content --slug
一键全搞定: python3 tools/front_matter.py content --slug --image --add-missing

脚本代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342


import os
import argparse
import logging
import sys
import re
import yaml
import requests
from pathlib import Path

# Try to import required libraries, if missing, we will catch ImportError later or let it fail
try:
 import frontmatter
 from slugify import slugify
 from deep_translator import GoogleTranslator
except ImportError:
 pass

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

class HugoContentProcessor:
 def __init__(self, content_dir, enable_slug=False, enable_pinyin=False, enable_image=False, add_missing=False):
 self.content_dir = Path(content_dir)
 self.enable_slug = enable_slug
 self.enable_pinyin = enable_pinyin # New flag for Pinyin
 self.enable_image = enable_image
 self.add_missing = add_missing
 # Initialize translator only if needed to avoid overhead or connection checks immediately
 self._translator = None

 @property
 def translator(self):
 if self._translator is None:
 self._translator = GoogleTranslator(source='auto', target='en')
 return self._translator

 def process(self):
 if not self.content_dir.exists():
 logger.error(f"Directory not found: {self.content_dir}")
 return

 logger.info(f"Scanning directory: {self.content_dir}")
 for root, dirs, files in os.walk(self.content_dir):
 for file in files:
 if file.endswith(('.md', '.markdown')):
 file_path = Path(root) / file
 self.process_file(file_path)

 def process_file(self, file_path):
 try:
 # Read file content as text to preserve formatting
 content = file_path.read_text(encoding='utf-8')

 # Extract Front Matter block using Regex
 # Matches content between the first two '---' lines
 match = re.search(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
 if not match:
 logger.debug(f"Skipped (no front matter): {file_path}")
 return

 fm_text = match.group(1)
 original_fm_text = fm_text

 # Use PyYAML just to parse the structure for logic checking
 try:
 metadata = yaml.safe_load(fm_text)
 except yaml.YAMLError:
 logger.warning(f"Skipped (invalid YAML): {file_path}")
 return

 if not metadata:
 return

 if self.enable_slug:
 fm_text = self._process_slug_logic(fm_text, metadata)

 if self.enable_image:
 fm_text = self._process_image_logic(fm_text, metadata, file_path)

 if fm_text != original_fm_text:
 # Reconstruct the full file content
 new_content = content[:match.start(1)] + fm_text + content[match.end(1):]

 file_path.write_text(new_content, encoding='utf-8')
 logger.info(f"Updated: {file_path}")
 else:
 logger.debug(f"Skipped (no changes): {file_path}")

 except Exception as e:
 logger.error(f"Failed to process {file_path}: {e}")

 def _process_slug_logic(self, fm_text, metadata):
 # 1. Check if 'slug' key exists
 slug_exists = 'slug' in metadata

 if not slug_exists and not self.add_missing:
 return fm_text

 # 2. Check if slug is already set (non-empty)
 existing_slug = metadata.get('slug')
 if existing_slug and str(existing_slug).strip():
 return fm_text

 # 3. Get Title for generation
 title = metadata.get('title')
 if not title:
 return fm_text

 # --- Generation Logic ---
 logger.info(f"Generating slug for title: '{title}'")
 slug_text = title

 # Check if translation is needed
 # Logic: If pinyin is enabled, skip translation and use title directly (slugify converts to pinyin)
 # Otherwise, translate non-English titles to English.
 if not self.enable_pinyin and not self.is_english(title):
 try:
 # Translate to English
 translated = self.translator.translate(title)
 slug_text = translated
 logger.info(f"Translated '{title}' to '{slug_text}'")
 except Exception as e:
 logger.warning(f"Translation failed for '{title}': {e}. Falling back to raw title.")

 new_slug = slugify(slug_text)

 if not new_slug:
 return fm_text

 # --- Text Replacement ---
 slug_pattern = r'^(\s*slug:)(\s*)$'

 def replace_callback(m):
 return f"{m.group(1)} {new_slug}"

 new_fm_text, count = re.subn(slug_pattern, replace_callback, fm_text, count=1, flags=re.MULTILINE)

 # If not found but we want to add new slugs
 if count == 0 and self.add_missing and not slug_exists:
 # Add slug field to the end of front matter
 if not fm_text.endswith('\n'):
 new_fm_text = fm_text + '\n'
 else:
 new_fm_text = fm_text

 new_fm_text += f"slug: {new_slug}\n"

 return new_fm_text

 def _process_image_logic(self, fm_text, metadata, file_path):
 # 1. Check if 'image' key exists
 image_exists = 'image' in metadata

 if not image_exists and not self.add_missing:
 return fm_text

 # 2. Check if image is already set (non-empty)
 existing_image = metadata.get('image')
 if existing_image and str(existing_image).strip():
 return fm_text

 # --- Check for existing image in the same directory (Multi-language support) ---
 # If we have index.zh.md and index.en.md, they share the same folder.
 # If cover.jpg exists, we should just use it instead of downloading a new one.
 parent_dir = file_path.parent
 existing_cover = self._find_existing_cover(parent_dir)

 if existing_cover:
 logger.info(f"Found existing image for {file_path.name}: {existing_cover}")
 image_filename = existing_cover
 else:
 # --- Download Logic ---
 title = metadata.get('title', '')
 # Prepare prompt for image generation
 prompt = self._generate_image_prompt(title, content_preview=None) # We could pass content if needed

 logger.info(f"Downloading image for: {file_path.name} with prompt: '{prompt}'")
 image_filename = self._download_image(parent_dir, prompt)

 if not image_filename:
 return fm_text

 # --- Text Replacement ---
 image_pattern = r'^(\s*image:)(\s*)$'

 def replace_callback(m):
 return f"{m.group(1)} {image_filename}"

 new_fm_text, count = re.subn(image_pattern, replace_callback, fm_text, count=1, flags=re.MULTILINE)

 # If not found but we want to add new image field
 if count == 0 and self.add_missing and not image_exists:
 # Add image field to the end of front matter
 if not fm_text.endswith('\n'):
 new_fm_text = fm_text + '\n'
 else:
 new_fm_text = fm_text

 new_fm_text += f"image: {image_filename}\n"
 else:
 new_fm_text = fm_text if count == 0 else new_fm_text

 return new_fm_text

 def _find_existing_cover(self, directory):
 """Look for common cover image filenames in the directory."""
 common_names = ['cover.jpg', 'cover.png', 'feature.jpg', 'featured.jpg', 'thumbnail.jpg']
 # Also check for any file starting with cover_

 try:
 for file in directory.iterdir():
 if file.is_file():
 if file.name.lower() in common_names:
 return file.name
 if file.name.lower().startswith('cover') and file.suffix.lower() in ['.jpg', '.png', '.jpeg', '.webp']:
 return file.name
 except Exception:
 pass
 return None

 def _generate_image_prompt(self, title, content_preview=None):
 """Translate title to English to serve as a prompt."""
 if not title:
 return "abstract minimal background"

 prompt = title
 if not self.is_english(title):
 try:
 translated = self.translator.translate(title)
 prompt = translated
 except Exception as e:
 logger.warning(f"Translation failed for prompt '{title}': {e}")

 # Add some style keywords to make the image better for a blog cover
 return f"{prompt}, aesthetic, minimalist, high quality, 4k, wallpaper"

 def _download_image(self, target_dir, prompt):
 # Determine strict save path
 filename = "cover.jpg"
 save_path = target_dir / filename

 # Ensure unique filename if cover.jpg exists and we are genuinely downloading new one
 # (Though logic outside should often catch existing ones, this is a safety net)
 counter = 1
 while save_path.exists():
 filename = f"cover_{counter}.jpg"
 save_path = target_dir / filename
 counter += 1

 # Common Headers to avoid being blocked (403/503)
 headers = {
 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
 }

 # Download from Picsum (Random high quality placeholders)
 try:
 logger.info(f"Downloading image from Picsum (Random)")
 url = "https://picsum.photos/1200/630"

 response = requests.get(url, headers=headers, timeout=20, allow_redirects=True)
 if response.status_code == 200:
 with open(save_path, 'wb') as f:
 f.write(response.content)
 logger.info(f"Saved image from Picsum to: {save_path}")
 return filename
 except Exception as e:
 logger.error(f"Download attempt failed: {e}")

 return None

 def is_english(self, text):
 """Check if text contains only ASCII characters."""
 try:
 text.encode(encoding='utf-8').decode('ascii')
 except UnicodeDecodeError:
 return False
 return True

def check_dependencies():
 missing = []
 try:
 import frontmatter
 except ImportError:
 missing.append("python-frontmatter")

 try:
 from slugify import slugify
 except ImportError:
 missing.append("python-slugify")

 try:
 from deep_translator import GoogleTranslator
 except ImportError:
 missing.append("deep-translator")

 if missing:
 print("Missing required libraries. Please install them:")
 print(f"pip install {' '.join(missing)}")
 sys.exit(1)

if __name__ == "__main__":
 check_dependencies()

 parser = argparse.ArgumentParser(
 description="Process Hugo content front matter to generate English slugs from titles and download cover images.",
 formatter_class=argparse.RawTextHelpFormatter,
 epilog="""
Examples:
 1. Default mode (No action by default now, must specify flag):
 python3 tools/front_matter.py content --slug

 2. Process images only:
 python3 tools/front_matter.py content --image

 3. Add missing slugs and images:
 python3 tools/front_matter.py content --slug --image --add-missing
"""
 )
 parser.add_argument("dir", nargs="?", default="content", help="Content directory to process (relative to current path)")
 parser.add_argument("--slug", action="store_true", help="Enable slug processing")
 parser.add_argument("--pinyin", action="store_true", help="Use Pinyin for slug generation instead of English translation")
 parser.add_argument("--image", action="store_true", help="Enable image processing (downloads from Picsum)")
 parser.add_argument("--add-missing", action="store_true", help="Add fields ('slug'/'image') if they are missing")
 args = parser.parse_args()

 # If neither is specified, maybe warn? Or just do nothing?
 if not (args.slug or args.image):
 parser.print_help()
 sys.exit(0)

 # Resolve absolute path
 base_dir = Path(os.getcwd())
 target_dir = base_dir / args.dir

 processor = HugoContentProcessor(
 target_dir,
 enable_slug=args.slug,
 enable_pinyin=args.pinyin,
 enable_image=args.image,
 add_missing=args.add_missing
 )
 processor.process()

Slug on 两点之间

Hugo小脚本：自动完善slug及image属性

主要功能

1. 自动生成 Slug

2. 自动下载封面图

3. 支持多语言

如何使用

脚本代码