pelican,一个成熟的 Python 库

大家好，我是木木。

今天给大家分享一个成熟的 Python 库，pelican。

pelican

如果你想做博客、文档站或者内容型官网，但又不想把整个发布流程都绑进数据库和后台系统，Pelican 这种“文本文件 + 配置 + 一次构建产出整站”的路线会很稳。它能把文章、页面、分类、标签、订阅源和多语言 URL 一起生成出来，对长期维护的静态内容项目尤其友好。

项目地址：https://github.com/getpelican/pelican

官方文档：https://docs.getpelican.com

三大特点

路由清楚

文章、页面、分类和标签都有明确输出规则，站点结构容易预判，也便于接入托管平台。

配置直白

很多能力直接靠配置项和文件元数据就能打开，不用一上来先写插件或后台逻辑。

产物完整

HTML、订阅源、静态资源和多语言路径能一起生成，很适合接 CI/CD 做自动发布。

最佳实践

安装方式：python -m pip install pelican markdown

为了让例子尽量贴近真实使用，这篇直接复用 Pelican 仓库自带的 samples/ 内容和配置文件，不额外捏造站点工程。重点看它怎么把一批文本内容稳定地编译成完整站点，以及配置和元数据能把输出路径控制到什么程度。

功能一：一次构建就能产出文章、页面、分类和订阅源

这段代码解决什么问题：很多静态站工具能把 Markdown 变成 HTML，但真正上线时你还得关心首页、分类页、测试页面和 RSS 有没有一起出来。Pelican 的命令行构建会把这些产物一次性整理好。

importosimportsubprocessimporttempfilefrompathlibimportPathPY=r"D:\Python\python3.11\python.exe"repo=Path.cwd()/"repo"env=os.environ.copy()env["PYTHONPATH"]=str(repo)withtempfile.TemporaryDirectory()astmp:out=Path(tmp)/"output"subprocess.run([PY,"-m","pelican",str(repo/"samples"/"content"),"-s",str(repo/"samples"/"pelican.conf.py"),"-o",str(out)],env=env,check=True,capture_output=True,text=True,)html_files=list(out.rglob("*.html"))xml_files=list(out.rglob("*.xml"))checks=["index.html","article-1.html","category/cat1.html","feeds/all.rss.xml","pages/this-is-a-test-page.html",]print("HTML :",len(html_files))print("XML  :",len(xml_files))forrelinchecks:print(rel,"=>",(out/rel).exists())

这种输出方式很适合内容站。你不是只得到几篇文章页面，而是把首页、归档、分类、页面和 feed 一起打包好，后面接 GitHub Pages、对象存储或 CDN 都比较顺。

功能二：文件元数据可以直接改输出路径，不必额外写路由脚本

这段代码解决什么问题：实际做内容站时，经常会遇到“这个页面要固定到某个目录”“某个标签页要覆盖默认地址”“文件名要自动推导 slug”这类需求。Pelican 把这些控制权放在源文件元数据里，改起来很直接。

importosimportsubprocessimporttempfilefrompathlibimportPathPY=r"D:\Python\python3.11\python.exe"repo=Path.cwd()/"repo"env=os.environ.copy()env["PYTHONPATH"]=str(repo)withtempfile.TemporaryDirectory()astmp:out=Path(tmp)/"output"subprocess.run([PY,"-m","pelican",str(repo/"samples"/"content"),"-s",str(repo/"samples"/"pelican.conf.py"),"-o",str(out)],env=env,check=True,capture_output=True,text=True,)mappings={"override_url_saveas.rst":"override/index.html","override_tag_oh.rst":"tag/oh.html","2012-11-30_filename-metadata.rst":"filename_metadata-example.html",}forsrc,relinmappings.items():print(src)print(" ->",rel,(out/rel).exists())

这点特别适合老站迁移和精细化内容运营。很多路由策略不用再塞到额外脚本里，直接写进内容文件或配置里，迁移和审查都会轻松很多。

环境与版本信息

• Demo 环境：Windows 11，Python 3.11，基于 getpelican/pelican 仓库源码运行
• 仓库当前版本：4.12.0
• 本文补齐的关键依赖：feedgenerator、ordered-set、rich
• GitHub 最近一次推送时间：2026-04-20T15:29:50Z
• pyproject.toml
   当前要求 Python >=3.11

高级功能

这段代码解决什么问题：静态站一旦做多语言，难点不只是翻译内容，还包括日期路径、语言版本文章和订阅源能不能一起跟着变。Pelican 可以直接用另一份配置把这些规则切到新的输出结构里。

importosimportsubprocessimporttempfilefrompathlibimportPathPY=r"D:\Python\python3.11\python.exe"repo=Path.cwd()/"repo"env=os.environ.copy()env["PYTHONPATH"]=str(repo)withtempfile.TemporaryDirectory()astmp:out=Path(tmp)/"output"subprocess.run([PY,"-m","pelican",str(repo/"samples"/"content"),"-s",str(repo/"samples"/"pelican.conf_FR.py"),"-o",str(out)],env=env,check=True,capture_output=True,text=True,)checks=[Path("posts/2011/février/17/article-1/index.html"),Path("posts/2012/février/29/second-article/index.html"),Path("oh-yeah-fr.html"),Path("feeds/all-fr.atom.xml"),]forrelinchecks:shown=rel.as_posix().encode("unicode_escape").decode()print(shown,"=>",(out/rel).exists())

这里最有价值的是，日期目录、法语文章和对应 feed 都能一起变成新的产物结构。对双语博客、国际化文档站或者多地区内容站来说，这种“换配置就换输出规则”的能力很实用。

适用场景

• 你要做博客、文档站或内容型官网，并且希望内容和配置都留在 Git 里
• 你希望分类、标签、feed、页面和静态资源一起走统一构建流程
• 你有多语言或历史 URL 兼容需求，想通过配置和元数据精细控制输出路径

不适用场景

• 你需要多人实时协作编辑、审批流和细颗粒权限管理的在线 CMS
• 你的网站高度依赖数据库查询、用户写入和实时交互，不只是静态发布
• 团队完全不想碰配置文件、模板和命令行，只想要纯可视化托管后台

上线检查

1. 先用真实内容跑一遍构建，确认文章、页面、分类和 feed 都按预期落到目标目录
2. 如果有旧站迁移需求，先把 url、save_as 和日期路径规则做一轮回归检查
3. 多语言站点上线前，单独检查各语言版本的输出目录、订阅源和 canonical URL

总结

如果你想要一套规则清楚、输出稳定、又能细致控制路径和语言版本的静态站工具，Pelican 依然很值得认真用起来。