企业官网建设流程全解析

Pelican 是一个用 Python 编写的静态站点生成器（Static Site Generator，SSG），允许开发者用自己熟悉的编辑器以 reStructuredText（reST）、Markdown 甚至 HTML 撰写内容，再通过简单的命令行工具生成完全静态的网站。本指南以官方文档首页（docs/index.rst）为核心脉络，结合仓库源码与配套文档，完整讲解 Pelican 的核心特性、快速上手流程、配置体系与发布部署方案，读完即可独立搭建并发布一个属于自己的静态博客。

一图看懂 Pelican 的工作方式

Pelican 的工作流可以概括为：输入内容 + 主题 + 配置 → 静态站点。官方文档首页配图直观地展示了这一过程：

从图中可以看到，Pelican 接收两类输入：一类是内容源（reStructuredText、Markdown、图片等），另一类是构建规则（Theme 主题与 Settings 设置）；经过 Pelican 处理后，产出包含 HTML 页面、RSS feeds、标签（Tags）和分类（Categories）的完整静态博客。整个过程不依赖数据库，也没有服务端运行时。

Pelican 是什么：项目定位与核心特性

根据 docs/index.rst 的官方定义，Pelican 是一个用 Python 编写的静态站点生成器，其定位与优势包括：

• 用你喜欢的编辑器写内容：支持 reStructuredText 与 Markdown 两种主流标记格式；
• 简单的 CLI 工具：一条命令即可（重新）生成站点；
• 易于对接版本控制与 Web hooks：内容就是纯文本文件，天然适合纳入 Git 等版本控制系统，并通过 CI 或 Webhook 自动发布；
• 完全静态的输出：生成的是纯 HTML/CSS/JS 文件，可以托管在任何静态文件服务上。

有趣的是，项目名 "Pelican" 是法语单词calepin（意为"笔记本"）的字母重排（anagram）。

特性清单与源码印证

文档首页列出的特性，在仓库中都有对应的具体实现：

源码级架构：Readers → Generators → Writer

从源码结构看，Pelican 的构建流程围绕三个核心模块展开（pelican/init.py 中的Pelican.run()方法将它们串在一起）：

1. Readers（读取器）：readers.py 中的BaseReader是读取文件的基类，定义了enabled、file_extensions等属性和read()方法；RstReader（readers.py）负责 reStructuredText，MarkdownReader负责 Markdown，均继承自BaseReader；
2. Generators（生成器）：generators.py 定义了ArticlesGenerator（L322）、PagesGenerator（L897）、StaticGenerator、TemplatePagesGenerator、SourceFileGenerator等生成器，分别负责收集文章、页面、静态文件并生成输出；Pelican._get_generator_classes()（pelican/init.py）负责装配生成器列表，其中StaticGenerator总是最后运行，以便识别被其他生成器跳过的文件；
3. Writer（写入器）：writers.py 中的Writer负责把渲染好的内容与订阅源写入输出目录。

30 秒快速上手：从零生成第一个站点

按照 docs/quickstart.rst 的指引，可以快速完成从安装到预览的完整流程。

第一步：安装

在 Python 3.11+（requires-python = ">=3.11"，见 pyproject.toml）环境中安装 Pelican。若计划使用 Markdown 写内容，推荐一并安装其可选依赖：

python -m pip install "pelican[markdown]"

如果权限不足，可在命令前加sudo。仓库的 pyproject.toml 表明，Pelican 的核心依赖还包括docutils（reST 解析）、jinja2（模板引擎）、pygments（语法高亮）、feedgenerator（订阅源生成）、unidecode（slug 处理）与watchfiles（文件监控）等。

第二步：创建项目骨架

为站点创建目录并进入：

mkdir -p ~/projects/yoursite cd ~/projects/yoursite

然后运行pelican-quickstart交互式命令生成项目骨架，它会询问一系列关于站点的问题：

pelican-quickstart

对带有默认值（方括号中）的问题，直接按回车接受默认值即可；当被问及 URL 前缀时，请输入你的域名，例如https://example.com。该命令还会生成pelicanconf.py（本地开发配置）与publishconf.py（发布配置）两个配置文件，以及可选的Makefile与tasks.py自动化脚本。

第三步：创建一篇文章

Pelican 在没有任何内容时无法运行。用文本编辑器创建第一篇 Markdown 文章：

Title: My First Review Date: 2010-12-03 10:20 Category: Review Following is a review of my favorite mechanical keyboard.

保存为~/projects/yoursite/content/keyboard-review.md。文件顶部以Title:、Date:、Category:开头的部分是文章元数据（metadata），Pelican 的读取器会解析这些字段并注入模板。

第四步：生成站点

在项目根目录运行pelican命令并指定内容目录：

pelican content

站点会生成在output/目录下。如果看到与订阅源相关的警告，属正常现象——本地开发时SITEURL尚未最终确定，可暂时忽略。

第五步：本地预览

打开一个新的终端会话，进入项目根目录，启动 Pelican 内置的 Web 服务器：

pelican --listen

然后在浏览器中访问 http://localhost:8000/ 即可预览站点。

CLI 常用参数速查

pelican命令的核心参数定义在 pelican/init.py 的parse_arguments()中，常用选项如下：

在main()（pelican/init.py）中，--autoreload与--listen可组合使用：Pelican 会启动两个进程，一个监听文件变更并重新生成，另一个提供 HTTP 服务，实现"保存即刷新"的开发体验。

配置体系：settings 文件详解

Pelican 通过一个 Python 模块文件（即.py文件）进行配置，详见 docs/settings.rst。仓库自带的示例配置位于 samples/pelican.conf.py。

配置文件如何生效

通过命令行传入配置文件：

pelican content -s path/to/your/pelicanconf.py

也可以直接用-e/--extra-settings以 JSON 格式覆盖任意设置，其优先级高于配置文件中的定义：

pelican content -e SITENAME='"A site"' READERS='{"html": null}' CACHE_CONTENT=true

使用环境变量时需注意转义：

pelican content -e API_KEY=''"$API_KEY"''

查看当前环境下的全部生效设置（可附加具体设置名只查看部分）：

pelican --print-settings

配置规则有三条硬性要求：

1. 所有设置标识符必须全大写，否则不会被处理（示例配置 samples/pelican.conf.py 中的小写变量foobar就是特意演示这一点的）；
2. 数字、布尔值、字典、元组等值不要加引号；字符串值必须加引号；
3. 路径类设置既可以是绝对路径，也可以是相对于配置文件的路径。

配置文件中定义的设置会传递给模板，因此可以用自定义设置向全站注入内容（如社交链接、菜单项等）。

基础设置（Basic settings）

以下是 docs/settings.rst 中基础设置的核心部分：

• USE_FOLDER_AS_CATEGORY：当文章元数据未指定分类时，若为True，文章所在子文件夹名即为其分类；为False则回退到DEFAULT_CATEGORY（默认"misc"）。默认值True；
• PATH：内容目录路径；OUTPUT_PATH：输出目录（默认"output"）；
• ARTICLE_PATHS/PAGE_PATHS：文章与页面的搜索目录列表，默认分别为[""]与["pages"]；配套的ARTICLE_EXCLUDES/PAGE_EXCLUDES用于排除目录；
• STATIC_PATHS：静态文件目录列表（默认["images"]），其中的文件会原样复制到输出目录而不做解析；
• SITENAME/SITEURL：站点名称与站点基础 URL。SITEURL默认是空字符串，官方建议务必显式指定，否则订阅源无法生成格式正确的 URL；HTTPS 站点应写为SITEURL = "https://example.com"（结尾不要带斜杠）；
• DELETE_OUTPUT_DIRECTORY：生成前删除输出目录（默认False）。这是破坏性设置，需谨慎使用；可通过OUTPUT_RETENTION列出应保留的文件（如[".git", ".hg", ".bzr"]）；
• READERS：文件扩展名与 Reader 类的映射。例如READERS = {"html": None}可跳过 HTML 文件处理，READERS = {"foo": FooReader}则为自定义扩展名注册读取器；
• IGNORE_FILES：Unix 风格 glob 模式列表，匹配的文件/目录会被忽略，默认["**/.*"]（忽略隐藏文件）；
• MARKDOWN：Markdown 处理器的额外配置，默认启用codehilite、extra、meta扩展并以 HTML5 输出；
• TYPOGRIFY：设为True时通过 Typogrify 库对生成 HTML 进行排版优化（如智能引号、破折号处理）；
• SUMMARY_MAX_LENGTH：自动生成文章摘要的默认词数（默认50）；
• WITH_FUTURE_DATES：若为False，日期在未来的内容会被标记为draft（草稿）状态。

URL 设置（URL settings）

Pelican 的 URL 体系支持相对与绝对两种模式：相对 URL 适合本地开发测试，绝对 URL 适合正式发布。官方推荐的实践是像pelican-quickstart那样维护pelicanconf.py（开发）与publishconf.py（发布）两套配置。

*_URL与*_SAVE_AS设置使用 Python 的格式化字符串，可用元数据占位符包括：slug、date、lang、author、category。例如：

ARTICLE_URL = "posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/" ARTICLE_SAVE_AS = "posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html" PAGE_URL = "pages/{slug}/" PAGE_SAVE_AS = "pages/{slug}/index.html"

这样文章会保存为posts/2011/Aug/07/sample-post/index.html，并可通过干净 URLposts/2011/Aug/07/sample-post/访问。若希望输出路径镜像源文件的目录结构，可配置：

PATH_METADATA = r"(?P<path_no_ext>.*)\..*" ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = "{path_no_ext}.html"

常用 URL 设置默认值（节选）：

若不需要某个默认页面（如单人博客不需要作者列表页），把对应*_SAVE_AS设为""即可禁用。

Pelican 还支持按年/月/日生成归档页，默认禁用，设置对应_SAVE_AS后自动启用：

YEAR_ARCHIVE_SAVE_AS = "posts/{date:%Y}/index.html" YEAR_ARCHIVE_URL = "posts/{date:%Y}/" MONTH_ARCHIVE_SAVE_AS = "posts/{date:%Y}/{date:%b}/index.html" MONTH_ARCHIVE_URL = "posts/{date:%Y}/{date:%b}/"

订阅源设置（Feed settings）

Pelican 默认使用 Atom 订阅源，也可改用 RSS。所有订阅源相关设置（FEED_ATOM、FEED_RSS、FEED_ALL_ATOM、FEED_ALL_RSS、CATEGORY_FEED_ATOM、TAG_FEED_RSS等）默认值为None表示不生成该订阅源，其中FEED_ALL_ATOM默认生成"feeds/all.atom.xml"（所有语言的文章）。{slug}占位符会替换为分类/作者/标签名。不需要的订阅源直接设为None即可。相关实现见 writers.py，Atom 与 RSS 使用不同的内容标签策略（RSS_FEED_SUMMARY_ONLY控制 RSS 的description中只放摘要还是全文）。

分页与排序设置

• DEFAULT_PAGINATION：每页最大文章数（默认False即不分页）；DEFAULT_ORPHANS：末页最少文章数；
• PAGINATION_PATTERNS：高级分页 URL 模式，由(minimum_page, page_url, page_save_as)三元组序列组成，可用{url}、{save_as}、{name}、{extension}、{base_name}、{number}变量。例如把第二页起放到page/2/路径下：

PAGINATION_PATTERNS = ( (1, "{url}", "{save_as}"), (2, "{base_name}/page/{number}/", "{base_name}/page/{number}/index.html"), )

• ARTICLE_ORDER_BY：文章排序方式，默认"reversed-date"（最新在前），可用reversed-前缀反转；
• REVERSE_CATEGORY_ORDER：反转分类的字母排序。

元数据处理设置

• FILENAME_METADATA：从文件名提取元数据的正则表达式，默认r"(?P<date>\d{4}-\d{2}-\d{2}).*"（从2026-04-30_blog-article.md这类文件名中提取日期）。也可提取多个字段，例如：

FILENAME_METADATA = r"(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)"

• PATH_METADATA：从相对路径提取元数据（如r"(?P<date>\d{4}/\d{2}/\d{2}).*"匹配2026/04/30.rst）；
• EXTRA_PATH_METADATA：按相对路径附加额外元数据，最具体的路径优先。一个经典用途是重定向静态文件的输出位置：

STATIC_PATHS = ["static/robots.txt"] EXTRA_PATH_METADATA = { "static/robots.txt": {"path": "robots.txt"}, }

• SLUGIFY_SOURCE：slug 生成来源，可选title（用标题）或basename（用文件名），默认"title"；SLUG_REGEX_SUBSTITUTIONS可自定义 slug 的正则替换规则。

主题与模板设置

内置两套主题可通过THEME设置或-t参数指定：

• notmyidea：默认主题；
• simple：极简纯文本风格主题。

指定主题的四种方式（见 docs/settings.rst 主题章节）：

THEME = "notmyidea" # 内置主题名 THEME = "chunk" # pelican-themes 工具安装的主题名 THEME = "themes/mycustomtheme" # 相对配置文件路径 THEME = "/home/myuser/projects/mysite/themes/mycustomtheme" # 绝对路径

相关设置包括：THEME_STATIC_DIR（主题静态文件输出目录，默认theme）、THEME_STATIC_PATHS（默认["static"]）、THEME_TEMPLATES_OVERRIDES（在主题模板之前搜索的覆盖模板路径）、CSS_FILE（默认main.css）。notmyidea 主题支持CSS_FILE = "wide.css"切换宽屏版式，还可通过SITESUBTITLE、DISQUS_SITENAME、GITHUB_URL、ANALYTICS、MENUITEMS、LINKS、SOCIAL等设置定制站点头部、评论区、社交链接等。

TEMPLATE_PAGES允许用 Jinja2 模板生成自定义页面：

TEMPLATE_PAGES = { "src/books.html": "dest/books.html", "src/resume.html": "dest/resume.html", "src/contact.html": "dest/contact.html", }

DIRECT_TEMPLATES（默认["index", "tags", "categories", "authors", "archives"]）决定直接渲染的集合页模板列表。

多语言与日期设置

• DEFAULT_LANG：默认语言（默认"en"）；ARTICLE_TRANSLATION_ID/PAGE_TRANSLATION_ID决定如何识别互为翻译的内容（默认按slug匹配）；
• TIMEZONE：用于生成订阅源日期信息的时区，若未定义则默认 UTC 并会收到警告；
• DEFAULT_DATE_FORMAT：默认日期格式（"%a %d %B %Y"）；DATE_FORMATS可按语言分别设置格式，甚至以(locale, format)元组覆盖LOCALE设置：

DATE_FORMATS = { "en": "%a, %d %b %Y", "jp": "%Y-%m-%d(%a)", }

插件机制：用信号扩展 Pelican

自 3.0 起 Pelican 支持插件，4.5 起引入基于命名空间包（namespace package）的新插件结构，可通过 Pip 直接安装（见 docs/plugins.rst）。插件会被自动发现并注册到pelican.plugins命名空间下，运行pelican-plugins可查看当前环境中已安装并激活的插件。

PLUGINS设置控制插件加载方式：保持默认None时自动发现所有命名空间插件；显式指定插件列表则关闭自动发现，只注册列出的插件。插件可用完整名称（pelican.plugins.myplugin）、短名称（myplugin）或直接传入已导入的模块：

PLUGINS = ['package.myplugin', 'namespace_plugin1', 'pelican.plugins.namespace_plugin2']

不在 Python 导入路径中的插件，可通过PLUGIN_PATHS指定搜索目录：

PLUGIN_PATHS = ["plugins", "/srv/pelican/plugins"] PLUGINS = ["assets", "liquid_tags", "sitemap"]

编写一个插件

插件的核心规则是：定义一个register可调用对象，在其中把信号（signal）连接到插件逻辑。信号在 pelican/plugins/signals.py 中定义，示例插件如下：

import logging from pelican import signals log = logging.getLogger(__name__) def test(sender): log.debug("%s initialized !!", sender) def register(): signals.initialized.connect(test)

需要注意，信号接收器是弱引用，因此不要在register函数内部定义接收器函数，否则可能在信号发出前被垃圾回收。若多个插件连接同一信号，调用顺序为注册顺序（PLUGINS列表顺序或自动发现顺序）。

常用信号包括：initialized（初始化后）、finalized（生成结束、退出前，适合做资源压缩、通知搜索引擎等后处理）、readers_init（注册自定义读取器）、article_generator_pretaxonomy（修改文章列表）、get_generators（注册自定义生成器）、get_writer（注册自定义写入器）、content_object_init（内容对象初始化）等。

三个实用插件配方

自定义读取器（支持新输入格式）：

from pelican import signals from pelican.readers import BaseReader class NewReader(BaseReader): enabled = True file_extensions = ['yeah'] # 匹配 .yeah 文件 def read(self, filename): metadata = {'title': 'Oh yeah', 'category': 'Foo', 'date': '2012-12-01'} parsed = {} for key, value in metadata.items(): parsed[key] = self.process_metadata(key, value) return "Some content", parsed def add_reader(readers): readers.reader_classes['yeah'] = NewReader def register(): signals.readers_init.connect(add_reader)

注入自定义内容（从 API 拉取文章等场景）：

import datetime from pelican import signals from pelican.contents import Article from pelican.readers import BaseReader def addArticle(articleGenerator): settings = articleGenerator.settings baseReader = BaseReader(settings) # 作者、分类、标签是对象而非字符串 newArticle = Article( "I am the body of an injected article!", { "title": "Injected Article!", "date": datetime.datetime.now(), "category": baseReader.process_metadata("category", "fromAPI"), "tags": baseReader.process_metadata("tags", "tagA, tagB"), }, ) articleGenerator.articles.insert(0, newArticle) def register(): signals.article_generator_pretaxonomy.connect(addArticle)

自定义写入器（输出额外文件格式或改变现有写入方式）：

from pelican.writers import Writer from pelican import signals class MyWriter(Writer): pass # 定义新的写入功能 def add_writer(pelican_object): return MyWriter def register(): signals.get_writer.connect(add_writer)

注意同一时刻只会有一个写入器生效，因此应继承内置Writer或完整重写。

发布与自动化部署

生成站点、本地预览之后，即可进入发布阶段（详见 docs/publish.rst）。

生成与预览

pelican /path/to/your/content/ [-s path/to/your/settings.py]

默认使用内置主题把站点输出到output/目录。开启自动重建 + 本地服务：

pelican --autoreload --listen

用浏览器直接打开output/index.html也可预览，但 CSS 等资源路径可能定位失败，更推荐使用内置服务器：pelican --listen，然后访问 http://localhost:8000/。

发布到服务器

使用publishconf.py重新生成生产版本（可先通过from pelicanconf import *继承开发配置）：

pelican content -s publishconf.py

若目标服务器支持 SSH（Nginx/Apache），可用rsync同步站点文件：

rsync -avc --delete output/ host.example.com:/var/www/your-site/

GitHub Pages 等托管方案的详细步骤见 docs/tips.rst。

自动化：Invoke 与 Make

pelican-quickstart可生成tasks.py（Invoke）与Makefile两套自动化脚本：

Invoke（Python 生态，需python -m pip install invoke）：

invoke build # 用 pelicanconf.py 生成站点 invoke regenerate # 文件变更时自动重新生成 invoke serve # 本地预览 http://localhost:8000/ invoke livereload # 带浏览器自动刷新（需安装 livereload） invoke publish # 通过 rsync over SSH 发布

Make（POSIX 内置，Windows 需自行安装）：

make html # 生成站点（pelicanconf.py） make publish # 生产构建（publishconf.py） make regenerate # 自动重新生成 make serve # 本地预览 make devserver # 同时运行 regenerate + serve make rsync_upload # 通过 rsync over SSH 发布

若需替换默认的python/pelican可执行文件，可设置PY与PELICAN环境变量。这些脚本只是"包装"了规范的pelican命令，随时可以删除，不影响命令本身的使用。

文档地图：继续深入

本文是 Pelican 文档体系的总入口（原 docs/index.rst 的 toctree 导航）。仓库还提供了以下高价值文档，可按需查阅：

• 快速开始：面向急性子的最短上手路径
• 安装指南：环境要求与安装细节
• 内容撰写：文章/页面的元数据、内部链接、翻译等
• 发布指南：生成、部署与自动化
• 设置参考：全部配置项的完整参考（本文为节选）
• 插件开发：信号列表与插件配方
• 主题开发：如何创建自己的 Jinja2 主题
• pelican-themes 工具：主题安装管理
• 内容导入：从 WordPress 等平台迁移
• FAQ 与 实用技巧：常见问题与进阶用法
• 内部实现：Pelican 架构原理
• 问题反馈与贡献：参与项目的方式
• 变更日志：版本演进记录

如需反馈问题或参与贡献，可参照 docs/contribute.rst 中的指南。通过本指南，你已经掌握了 Pelican 从安装、写文、配置、定制主题到发布部署的完整链路，可以在此基础上按需深入任意环节。