企业官网建设流程全解析

导读

本指南以仓库测试夹具 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 dog's 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（代码高亮）与extra（Markdown 扩展集），并指定output_format: "html5"（settings.py）。

2. Setext 标题

正文使用Setext 风格标题：

Test Markdown File Header ========================= # H1，由 = 下划线标记 Used for pelican test --------------------- # H2，由 - 下划线标记

在测试 test_readers.py 中，这份文档的期望渲染结果是：

<h1>Test Markdown File Header</h1> <h2>Used for pelican test</h2> <p>The quick brown fox jumped over the lazy dog's 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）：

注意：元数据键在解析时会被统一转为小写（name = name.lower()，readers.py），所以Title:与title:效果相同。对于date、status等不允许重复定义的键，若出现多次定义会记录警告并使用第一个值（readers.py）。

3. status 的四种取值

status决定页面归属的集合（generators.py）：

• published（默认）：进入pages，正常渲染到输出目录；
• hidden：进入hidden_pages，渲染但不显示在导航菜单；
• draft：进入draft_pages，渲染到草稿目录（默认drafts/pages/{slug}.html）；
• skip：由Readers.read_file转为SkipStub，直接跳过不生成（readers.py）。

仓库在 draft_page_markdown.md（status: draft）与 hidden_page_markdown.md（status: hidden）中给出了同构的对照样例——三份文件标题结构完全一致，仅元数据与尾句不同，非常便于观察状态字段的差异。

三、页面与文章：两种内容类型的分工

Pelican 将内容分为 Article（博客文章）与 Page（页面）两类。二者的核心差异在 contents.py 中一览无余：

因此"关于我""联系方式""项目介绍"等静态内容适合写成 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.py）：

1. default_metadata()：来自DEFAULT_METADATA、DEFAULT_CATEGORY、DEFAULT_DATE设置；
2. path_metadata()与parse_path_metadata()：从文件路径提取的元数据（如FILENAME_METADATA正则）；
3. 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 页面直接相关的默认配置如下：

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即pages）：

title: 关于本站 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 中编写静态页面的通用范式。