Pelican 静态页面（Pages）Markdown 编写指南：从最小示例到源码解析-北京尧图网络

【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址https://gitcode.com/gh_mirrors/pe/pelican点击查看免费下载导读本指南以仓库测试夹具 page_markdown.md 为标本系统讲解 Pelican基于 Python 的静态站点生成器中页面Page型内容的 Markdown 编写规范包括元数据块语法、Setext/ATX 标题结构、status状态语义、页面与文章的差异以及从MarkdownReader到PagesGenerator的完整处理链路。读完本文你将能够独立编写规范、可复现的 Markdown 页面并理解它最终如何被解析、分类、排序并输出为 HTML。一、page_markdown.md一个最小可用的 Markdown 页面该文件的完整内容仅 9 行却浓缩了 Pelican Markdown 页面的三个核心组成部分title: This is a markdown test page Test Markdown File Header Used for pelican test --------------------- The quick brown fox jumped over the lazy dogs back.1. 元数据块Metadata Block文件首行title: This is a markdown test page是YAML 风格的键值对元数据。Pelican 借助 Python-Markdown 的meta扩展解析该区域并以空行将其与正文分隔。在 readers.py 的MarkdownReader中这一行为是强制启用的if markdown.extensions.meta not in settings[extensions]: settings[extensions].append(markdown.extensions.meta)即使你的pelicanconf.py未显式声明markdown.extensions.meta也会被自动追加到扩展列表readers.py。默认的MARKDOWN配置还包含codehilite代码高亮与extraMarkdown 扩展集并指定output_format: html5settings.py。2. Setext 标题正文使用Setext 风格标题Test Markdown File Header # H1由下划线标记 Used for pelican test --------------------- # H2由 - 下划线标记在测试 test_readers.py 中这份文档的期望渲染结果是h1Test Markdown File Header/h1 h2Used for pelican test/h2 pThe quick brown fox jumped over the lazy dogs back./p可见 Setext 的对应h1、-对应h2正文段落被包进p。你也可以改用 ATX 风格#/##两种写法对 Pelican 而言等价。3. 正文标题之后的普通段落即页面正文。Pelican 不会对正文做额外限制Markdown 语法列表、链接、图片、代码块均可直接使用。二、页面的元数据字段与状态语义1. 必填项只有 title与文章Article不同页面Page的必填元数据只有title一项。源码 contents.py 中定义class Page(Content): mandatory_properties (title,) allowed_statuses (published, hidden, draft, skip) default_status published default_template page缺失title的页面会在Content.is_valid()校验阶段被判为无效并被跳过contents.py。2. 可选元数据除title外页面还可使用以下常用字段经readers.METADATA_PROCESSORS处理readers.py字段说明statuspublished/hidden/draft/skip默认publisheddate/modified日期会经get_date()解析category/author/authors分类、作者authors支持逗号或分号分隔tags标签列表slugURL 别名未提供时从文件名推导summary摘要可包含 Markdown 格式注意元数据键在解析时会被统一转为小写name name.lower()readers.py所以Title:与title:效果相同。对于date、status等不允许重复定义的键若出现多次定义会记录警告并使用第一个值readers.py。3. status 的四种取值status决定页面归属的集合generators.pypublished默认进入pages正常渲染到输出目录hidden进入hidden_pages渲染但不显示在导航菜单draft进入draft_pages渲染到草稿目录默认drafts/pages/{slug}.htmlskip由Readers.read_file转为SkipStub直接跳过不生成readers.py。仓库在 draft_page_markdown.mdstatus: draft与 hidden_page_markdown.mdstatus: hidden中给出了同构的对照样例——三份文件标题结构完全一致仅元数据与尾句不同非常便于观察状态字段的差异。三、页面与文章两种内容类型的分工Pelican 将内容分为 Article博客文章与 Page页面两类。二者的核心差异在 contents.py 中一览无余维度PageArticle必填元数据仅titletitledate默认模板pagearticle归档/订阅不进入文章流进入索引、归档与 Feed分类/作者一般不用默认按目录生成分类因此关于我联系方式项目介绍等静态内容适合写成 Page而带日期的博文应写成 Article。同目录下 page.rst 展示了同一页面的 reST 写法说明 Pelican 对两种语法一视同仁选择取决于你的内容习惯。四、从源码看 Markdown 页面的解析链路1. 扩展名路由MarkdownReader支持的扩展名包括md、markdown、mkd、mdown四种readers.py。Readers.read_file()根据文件后缀在注册表中查找对应 Reader若安装了markdown包则启用否则会在日志中提示安装readers.py。测试 test_readers.py 专门验证了md/mkd/markdown/mdown四种后缀都能被正确路由并产出相同 HTML这解释了为何仓库中同时存在.md、.mkd、.markdown、.mdown的样例文件。2. 元数据合并顺序read_file()依次合并四类元数据readers.pydefault_metadata()来自DEFAULT_METADATA、DEFAULT_CATEGORY、DEFAULT_DATE设置path_metadata()与parse_path_metadata()从文件路径提取的元数据如FILENAME_METADATA正则Reader 解析出的文件内元数据如page_markdown.md中的title。文件内元数据最后写入因此优先级最高——这就是为什么page_markdown.md的title能覆盖默认值。3. 页面的分类、排序与输出PagesGenerator.generate_context()遍历PAGE_PATHS下的文件排除PAGE_EXCLUDES按状态分流到pages/hidden_pages/draft_pages再按PAGE_ORDER_BY排序generators.py。随后generate_output()将每个页面交给 Writer结合模板渲染并写入save_as路径。五、相关配置项速查在 settings.py 中与 Markdown 页面直接相关的默认配置如下配置项默认值说明PAGE_PATHS[pages]页面源文件目录必须为列表误配为字符串会回退默认值PAGE_EXCLUDES[]需要排除的页面路径PAGE_URLpages/{slug}.html页面 URL 格式PAGE_SAVE_ASpages/{slug}.html页面输出文件路径PAGE_ORDER_BYbasename页面排序字段DRAFT_PAGE_SAVE_ASdrafts/pages/{slug}.html草稿页面输出路径MARKDOWN见 settings.pyMarkdown 扩展与输出格式TYPOGRIFYFalse开启后对正文、标题、摘要应用智能排版ARTICLE_PATHS与PAGE_PATHS会自动互相加入对方的排除列表避免同一文件被两种生成器重复处理settings.py。排序逻辑在PagesGenerator中经order_content(origs, self.settings[PAGE_ORDER_BY])生效测试 test_generators.py 展示了默认按文件名排序与设置PAGE_ORDER_BY title后按标题排序的两种结果。六、实战写一个自己的 Markdown 页面参照page_markdown.md在站点根目录创建content/pages/about.md若项目使用默认配置PAGE_PATHS即pagestitle: 关于本站 status: published # 关于本站这是一个用 Markdown 编写的 Pelican 页面。 - 支持 Setext 与 ATX 两种标题 - 支持 codehilite 代码高亮 - 支持 extra 扩展表格、脚注等构建后它会被解析为Page对象并输出到output/pages/about.html由PAGE_SAVE_AS决定。若希望页面暂不对外可见将status改为draft或hidden即可分别进入草稿目录或从导航隐藏。七、小结page_markdown.md虽小却完整示范了 Pelican Markdown 页面的全部关键要素YAML 风格元数据块title必填、Setext/ATX 标题、四种status语义以及被MarkdownReader解析、经PagesGenerator分流排序、最终渲染输出的整条流水线。理解这份最小样例就等于掌握了在 Pelican 中编写静态页面的通用范式。赞分享【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址https://gitcode.com/gh_mirrors/pe/pelican点击查看免费下载相关推荐Pelican reStructuredText 页面编写详解从 RST 页面到 Vercel 静态构建验证Pelican reStructuredText 页面编写详解从 RST 页面到 Vercel 静态构建验证本篇技术指南以 Vercel 开源仓库中 pacCLI后端云原生Gatsby 中使用 Markdown 文件生成页面using-markdown-pages 示例全解析Gatsby 中使用 Markdown 文件生成页面using markdown pages 示例全解析导读本文围绕 Gatsby 官方仓库中的 usin前端静态站点Web框架Pelican 静态页面Pages机制实战从测试样本 page.rst 理解页面文件格式与生成流程Pelican 静态页面Pages机制实战从测试样本 page.rst 理解页面文件格式与生成流程 Pelican 将内容分为文章Articles与静创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Pelican 静态页面（Pages）Markdown 编写指南：从最小示例到源码解析

相关推荐

推荐系统技术深度与技术品味

AI Agent 通信协议深度解析：从 MCP 工具互联到 A2A 多智能体协作（easy-vibe 实战视角）

使用 PHP Console Highlighter 在终端中高亮 PHP 代码：安装、API 与源码原理剖析

更多资讯

“cua”是什么梗？从游戏音效到全网热词的破圈密码

ArXiv每日CV论文自动抓取与筛选：从信息过载到精准复现

AI-Edge边缘AI部署实战：模型转换、量化与推理加速全解析

3个坑让轻松背单词项目提速50% 实战项目性能优化实录

国家重点研发计划资金管理：从预算编制到结题审计的合规实操指南

告别版本升级API全变:一文搞懂pf79性能优化实战

今日更新

2k显示屏性能优化踩坑：版本升级后API全变了，这份源码解析救了我

3步搞定美眉图实战项目，告别官方文档抓不住重点

3步搞定黄金大劫案项目搭建从入门到精通

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？