Pelican 静态站点生成器完全指南：基于 Markdown 与 reStructuredText 的 Python 建站方案

【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址https://gitcode.com/gh_mirrors/pe/pelican点击查看免费下载Pelican 是一个用 Python 编写的静态站点生成器Static Site GeneratorSSG允许开发者用自己熟悉的编辑器以 reStructuredTextreST、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。特性清单与源码印证文档首页列出的特性在仓库中都有对应的具体实现特性说明仓库依据文章与页面支持按时间排序的文章如博客文章与静态页面如 About、Projects、Contactcontents.py 定义Article与Page内容模型外部服务集成可接入 Disqus 评论、Google Analytics 等主题模板与 settings.rst 中的DISQUS_SITENAME、ANALYTICS等设置站点主题基于 Jinja2 模板引擎创建主题pelican/themes/ 内置notmyidea与simple两套主题多语言发布文章与页面支持翻译与多语言版本ARTICLE_LANG_URL、DEFAULT_LANG等设置见 settings.rstAtom / RSS 订阅源自动生成订阅源writers.py 中的_create_new_feed基于Atom1Feed/Rss201rev2Feed实现代码语法高亮通过 Pygments 实现pyproject.toml 声明了pygments依赖内容导入从 WordPress、Dotclear 或 RSS 导入已有内容tools/pelican_import.pyCLI 入口为pelican-import快速重建内容缓存与选择性输出写入CACHE_CONTENT、LOAD_CONTENT_CACHE等缓存设置见 settings.rst插件生态通过信号机制扩展无需修改核心代码docs/plugins.rst 与 pelican/plugins/signals.py源码级架构Readers → Generators → Writer从源码结构看Pelican 的构建流程围绕三个核心模块展开pelican/init.py 中的Pelican.run()方法将它们串在一起Readers读取器readers.py 中的BaseReader是读取文件的基类定义了enabled、file_extensions等属性和read()方法RstReaderreaders.py负责 reStructuredTextMarkdownReader负责 Markdown均继承自BaseReaderGenerators生成器generators.py 定义了ArticlesGeneratorL322、PagesGeneratorL897、StaticGenerator、TemplatePagesGenerator、SourceFileGenerator等生成器分别负责收集文章、页面、静态文件并生成输出Pelican._get_generator_classes()pelican/init.py负责装配生成器列表其中StaticGenerator总是最后运行以便识别被其他生成器跳过的文件Writer写入器writers.py 中的Writer负责把渲染好的内容与订阅源写入输出目录。30 秒快速上手从零生成第一个站点按照 docs/quickstart.rst 的指引可以快速完成从安装到预览的完整流程。第一步安装在 Python 3.11requires-python 3.11见 pyproject.toml环境中安装 Pelican。若计划使用 Markdown 写内容推荐一并安装其可选依赖python -m pip install pelican[markdown]如果权限不足可在命令前加sudo。仓库的 pyproject.toml 表明Pelican 的核心依赖还包括docutilsreST 解析、jinja2模板引擎、pygments语法高亮、feedgenerator订阅源生成、unidecodeslug 处理与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:开头的部分是文章元数据metadataPelican 的读取器会解析这些字段并注入模板。第四步生成站点在项目根目录运行pelican命令并指定内容目录pelican content站点会生成在output/目录下。如果看到与订阅源相关的警告属正常现象——本地开发时SITEURL尚未最终确定可暂时忽略。第五步本地预览打开一个新的终端会话进入项目根目录启动 Pelican 内置的 Web 服务器pelican --listen然后在浏览器中访问 http://localhost:8000/ 即可预览站点。CLI 常用参数速查pelican命令的核心参数定义在 pelican/init.py 的parse_arguments()中常用选项如下参数说明path内容目录路径位置参数-o/--output输出目录默认output-s/--settings配置文件路径默认自动寻找pelicanconf.py-t/--theme-path主题路径默认使用内置主题-r/--autoreload内容变更时自动重新生成-l/--listen启动 HTTP 服务默认端口 8000-p/--port指定监听端口-b/--bind指定绑定 IP默认 127.0.0.1-d/--delete-output-directory生成前删除输出目录-D/--debug显示调试日志--print-settings打印当前生效的配置并退出-e/--extra-settings以KEYVALUE形式覆盖配置VALUE 须为 JSON 格式--ignore-cache忽略此前构建的内容缓存在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 SITENAMEA site READERS{html: null} CACHE_CONTENTtrue使用环境变量时需注意转义pelican content -e API_KEY$API_KEY查看当前环境下的全部生效设置可附加具体设置名只查看部分pelican --print-settings配置规则有三条硬性要求所有设置标识符必须全大写否则不会被处理示例配置 samples/pelican.conf.py 中的小写变量foobar就是特意演示这一点的数字、布尔值、字典、元组等值不要加引号字符串值必须加引号路径类设置既可以是绝对路径也可以是相对于配置文件的路径。配置文件中定义的设置会传递给模板因此可以用自定义设置向全站注入内容如社交链接、菜单项等。基础设置Basic settings以下是 docs/settings.rst 中基础设置的核心部分USE_FOLDER_AS_CATEGORY当文章元数据未指定分类时若为True文章所在子文件夹名即为其分类为False则回退到DEFAULT_CATEGORY默认misc。默认值TruePATH内容目录路径OUTPUT_PATH输出目录默认outputARTICLE_PATHS/PAGE_PATHS文章与页面的搜索目录列表默认分别为[]与[pages]配套的ARTICLE_EXCLUDES/PAGE_EXCLUDES用于排除目录STATIC_PATHS静态文件目录列表默认[images]其中的文件会原样复制到输出目录而不做解析SITENAME/SITEURL站点名称与站点基础 URL。SITEURL默认是空字符串官方建议务必显式指定否则订阅源无法生成格式正确的 URLHTTPS 站点应写为SITEURL https://example.com结尾不要带斜杠DELETE_OUTPUT_DIRECTORY生成前删除输出目录默认False。这是破坏性设置需谨慎使用可通过OUTPUT_RETENTION列出应保留的文件如[.git, .hg, .bzr]READERS文件扩展名与 Reader 类的映射。例如READERS {html: None}可跳过 HTML 文件处理READERS {foo: FooReader}则为自定义扩展名注册读取器IGNORE_FILESUnix 风格 glob 模式列表匹配的文件/目录会被忽略默认[**/.*]忽略隐藏文件MARKDOWNMarkdown 处理器的额外配置默认启用codehilite、extra、meta扩展并以 HTML5 输出TYPOGRIFY设为True时通过 Typogrify 库对生成 HTML 进行排版优化如智能引号、破折号处理SUMMARY_MAX_LENGTH自动生成文章摘要的默认词数默认50WITH_FUTURE_DATES若为False日期在未来的内容会被标记为draft草稿状态。URL 设置URL settingsPelican 的 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(?Ppath_no_ext.*)\..* ARTICLE_URL ARTICLE_SAVE_AS PAGE_URL PAGE_SAVE_AS {path_no_ext}.html常用 URL 设置默认值节选设置默认值说明ARTICLE_URL/ARTICLE_SAVE_AS{slug}.html文章 URL 与保存路径ARTICLE_LANG_URL/ARTICLE_LANG_SAVE_AS{slug}-{lang}.html非默认语言文章的 URLDRAFT_URL/DRAFT_SAVE_ASdrafts/{slug}.html草稿文章的 URLPAGE_URL/PAGE_SAVE_ASpages/{slug}.html页面的 URLAUTHOR_URL/AUTHOR_SAVE_ASauthor/{slug}.html作者页CATEGORY_URL/CATEGORY_SAVE_AScategory/{slug}.html分类页TAG_URL/TAG_SAVE_AStag/{slug}.html标签页ARCHIVES_SAVE_ASarchives.html归档页INDEX_SAVE_ASindex.html首页若不需要某个默认页面如单人博客不需要作者列表页把对应*_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 settingsPelican 默认使用 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.pyAtom 与 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(?Pdate\d{4}-\d{2}-\d{2}).*从2026-04-30_blog-article.md这类文件名中提取日期。也可提取多个字段例如FILENAME_METADATA r(?Pdate\d{4}-\d{2}-\d{2})_(?Pslug.*)PATH_METADATA从相对路径提取元数据如r(?Pdate\d{4}/\d{2}/\d{2}).*匹配2026/04/30.rstEXTRA_PATH_METADATA按相对路径附加额外元数据最具体的路径优先。一个经典用途是重定向静态文件的输出位置STATIC_PATHS [static/robots.txt] EXTRA_PATH_METADATA { static/robots.txt: {path: robots.txt}, }SLUGIFY_SOURCEslug 生成来源可选title用标题或basename用文件名默认titleSLUG_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默认语言默认enARTICLE_TRANSLATION_ID/PAGE_TRANSLATION_ID决定如何识别互为翻译的内容默认按slug匹配TIMEZONE用于生成订阅源日期信息的时区若未定义则默认 UTC 并会收到警告DEFAULT_DATE_FORMAT默认日期格式%a %d %B %YDATE_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若目标服务器支持 SSHNginx/Apache可用rsync同步站点文件rsync -avc --delete output/ host.example.com:/var/www/your-site/GitHub Pages 等托管方案的详细步骤见 docs/tips.rst。自动化Invoke 与 Makepelican-quickstart可生成tasks.pyInvoke与Makefile两套自动化脚本InvokePython 生态需python -m pip install invokeinvoke build # 用 pelicanconf.py 生成站点 invoke regenerate # 文件变更时自动重新生成 invoke serve # 本地预览 http://localhost:8000/ invoke livereload # 带浏览器自动刷新需安装 livereload invoke publish # 通过 rsync over SSH 发布MakePOSIX 内置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 从安装、写文、配置、定制主题到发布部署的完整链路可以在此基础上按需深入任意环节。赞分享【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址https://gitcode.com/gh_mirrors/pe/pelican点击查看免费下载相关推荐Pelican 静态站点生成器完全指南从 Markdown/reST 内容到静态网站的原理与实践Pelican 静态站点生成器完全指南从 Markdown/reST 内容到静态网站的原理与实践 Pelican 是一个用 Python 编写的静态站点生成器Pelican静态网站终极指南掌握Markdown和reStructuredText语法Pelican静态网站终极指南掌握Markdown和reStructuredText语法 Pelican是一个基于Python的静态网站生成器支持MarkdCobalt.rs基于Rust的静态站点生成器指南Cobalt.rs基于Rust的静态站点生成器指南 项目概述 Cobalt.rs 是一个使用Rust编程语言编写的高效静态网站生成工具。它为开发者提供了一个强开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考