Pelican 排版美化实战深入解析 TYPOGRIFY_DASHES 与破折号处理机制【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址: https://gitcode.com/gh_mirrors/pe/pelican导读本文围绕 Pelican 测试夹具 article_with_typogrify_dashes.rst 展开讲解静态站点生成器 Pelican 中 Typogrify 排版增强功能的破折号处理原理。通过该夹具文件与 test_readers.py 中的断言测试你将完整掌握TYPOGRIFY_DASHES三种模式default/oldschool/oldschool_inverted对-、--、---连字符序列的 HTML 实体转换规则以及如何在pelicanconf.py中正确配置让生成的文章排版达到专业出版级水准。一、夹具文件一行标题里的排版玄机在 Pelican 仓库的 pelican/tests/content/ 目录下存在一个仅有 4 行的 RST 测试文件 article_with_typogrify_dashes.rstOne -, two --, three --- dashes! ################################ One: -; Two: --; Three: ---它不是一个普通的示例文章而是一个精心设计的测试夹具fixture第一行同时充当文章标题与元数据来源正文则通过三种连字符序列-、--、---来探测 Typogrify 在不同配置下的行为。与之对应仓库还提供了同名的 Markdown 版本 article_with_typogrify_dashes.md用于验证MdReader走的是同一条排版管道Title: One -, two --, three --- dashes! One: -; Two: --; Three: ---两个文件的核心差异在于标题的声明方式RST 用标题下划线####声明Markdown 用Title:元数据声明。而它们被设计为输出完全相同的渲染结果这正是测试的意图——无论你使用哪种内容格式破折号排版行为应当一致。二、背景Typogrify 是什么Pelican 如何接入Typogrify 是一套 Python 排版增强库它通过多个过滤器改善 HTML 的可读性主要包括smartypants把 ASCII 引号、连字符等替换为印刷级的智能引号与破折号en-dash–、em-dash—amp把裸规范为amp;caps为全大写缩写添加span classcaps样式initial_quotes处理段落开头的引号widont阻止标题/段落最后一行只剩一个单词避免孤行。在 Pelican 中Typogrify 属于可选依赖官方文档 docs/settings.rst 明确指出安装方式python -m pip install typogrify安装后在 pelicanconf.py 中开启开关即可。Pelican 的默认配置定义在 pelican/settings.pyTYPOGRIFY: False, TYPOGRIFY_IGNORE_TAGS: [], TYPOGRIFY_OMIT_FILTERS: [], TYPOGRIFY_DASHES: default,注意TYPOGRIFY默认是False这意味着默认构建不启用任何排版增强只有显式开启后破折号处理才会生效。三、TYPOGRIFY_DASHES三种破折号模式的完整对照TYPOGRIFY_DASHES控制 smartypants 过滤器如何解释多连字符序列。官方文档 docs/settings.rst 的说明可归纳为下表配置值单连字符-双连字符--三连字符---default保持为 hyphen-转为 em-dash—转为 em-dash hyphen— -oldschool保持为 hyphen-转为 en-dash–转为 em-dash—oldschool_inverted保持为 hyphen-转为 em-dash—转为 en-dash–用测试断言中的 HTML 实体表示#8211;即–#8212;即—nbsp;即不换行空格配置值输入-输入--输入---default-#8212;#8212;-oldschool-#8211;#8212;oldschool_inverted-#8212;#8211;三条规则的核心要点单连字符永远是连字符。无论哪种模式单个-都不会被转换因为它在英文排版中承担的是复合词连接符hyphen职能如 well-knowndefault不处理 en-dash。它只把双连字符折叠成 em-dash这也是 Typogrify/smartypants 最经典的行为对应 smartypants 内部的set1oldschool与oldschool_inverted是互逆的两套旧式映射。前者遵循传统打字机习惯--→en-dash---→em-dash后者则相反--→em-dash---→en-dash。3.1 从测试断言看三种模式的真实输出RST 版本对应的测试 test_readers.py#L588-L623 给出了精确的期望输出default 模式expected pOne: -; Two: #8212;; Three:nbsp;#8212;-/p\n expected_title One -, two #8212;, three #8212;-nbsp;dashes!正文中Two: --变为Two: #8212;em-dashThree: ---变为Three:nbsp;#8212;-em-dash hyphen标题中--- dashes变为#8212;-nbsp;dashes末尾单词前被插入了nbsp;——这是widont 过滤器在起作用防止标题最后一行只剩 dashes! 一个孤词。oldschool 模式expected pOne: -; Two: #8211;; Three:nbsp;#8212;/p\n expected_title One -, two #8211;, three #8212;nbsp;dashes!--转 en-dash#8211;---转 em-dash#8212;。oldschool_inverted 模式expected pOne: -; Two: #8212;; Three:nbsp;#8211;/p\n expected_title One -, two #8212;, three #8211;nbsp;dashes!--转 em-dash#8212;---转 en-dash#8211;与 oldschool 完全对调。Markdown 版本的测试位于 test_readers.py#L863-L898期望输出与 RST 版本逐字符一致唯一区别是 Markdown 渲染的段落末尾没有\n。这印证了两个格式在排版管道上是等价的。四、源码级原理readers.py 中的 smartypants 装配破折号转换发生在文章内容读取阶段。核心实现在 pelican/readers.py#L635-L680 的Readers.read_file()方法中执行顺序如下开关判断if self.settings[TYPOGRIFY]:才进入排版流程延迟导入import smartypants与from typogrify.filters import typogrify放在函数内部因为 typogrify 是可选依赖未安装时不应报错按配置选择映射集readers.py#L641-L647typogrify_dashes self.settings[TYPOGRIFY_DASHES] if typogrify_dashes oldschool: smartypants.Attr.default smartypants.Attr.set2 elif typogrify_dashes oldschool_inverted: smartypants.Attr.default smartypants.Attr.set3 else: smartypants.Attr.default smartypants.Attr.set1这里set1、set2、set3正是上一节三种模式的底层实现set1default把--折叠为 em-dash 且不产生 en-dashset2oldschool让--→en-dash、---→em-dashset3oldschool_inverted则反过来。兼容 Docutils 的引号处理readers.py#L649-L653代码额外设置smartypants.Attr.default | smartypants.Attr.w并附注释说明原因——DocutilsRST 渲染器在 smartypants 运行之前已经先把双引号替换成了quot;实体因此必须让 smartypants 也替换quot;才能正确生成智能引号作用范围readers.py#L673-L680排版过滤依次应用于content正文、metadata[title]标题、metadata[summary]摘要这也是测试中标题也会出现nbsp;与实体转换的原因。4.1 兼容性回退逻辑readers.py#L655-L671 中的typogrify_wrapper采用 try/except 链保证老版本 Typogrify 也能工作优先使用带TYPOGRIFY_IGNORE_TAGS和TYPOGRIFY_OMIT_FILTERS的完整签名若抛TypeError说明旧版不支持这些参数则降级为只传忽略标签再失败则只调用最基础的typogrify(text)。五、实战在 pelicanconf.py 中配置破折号风格启用并定制破折号处理只需在 pelicanconf.py或publishconf.py中加入如下配置# 启用 Typogrify 排版增强可选依赖需先安装python -m pip install typogrify TYPOGRIFY True # 破折号映射风格可选值 # default -- 双连字符转为 em-dash不产生 en-dash默认值 # oldschool -- 双连字符转为 en-dash三连字符转为 em-dash # oldschool_inverted -- 双连字符转为 em-dash三连字符转为 en-dash TYPOGRIFY_DASHES default # 可选跳过某些标签默认 Typogrify 会忽略 pre 与 code见下节 TYPOGRIFY_IGNORE_TAGS [] # 可选跳过某些过滤器允许值见下节 TYPOGRIFY_OMIT_FILTERS []配置后重新生成站点即可看到效果pelican content -s pelicanconf.py从源码结构可以推断TYPOGRIFY在 readers.py 中按文章逐篇生效因此任何新生成的 HTML 都会自动应用排版规则无需改动模板。六、相关配置项与使用限制6.1 TYPOGRIFY_IGNORE_TAGS官方文档 docs/settings.rst#L313-L317 说明这是一个让 Typogrify 忽略的标签列表。默认 Typogrify 会忽略pre和code标签以保护代码块不被引号/连字符转换破坏测试 test_readers.py#L496-L556 专门验证了这一点。默认值为[]即不额外忽略任何标签该特性要求 Typogrify 版本不低于 2.0.4。6.2 TYPOGRIFY_OMIT_FILTERS官方文档 docs/settings.rst#L319-L325 说明允许跳过的过滤器包括amp、smartypants、caps、initial_quotes、widont。例如若你只想保留破折号/引号转换而不想要孤行控制可设置TYPOGRIFY_OMIT_FILTERS [widont]默认值为[]应用全部过滤器该特性要求 Typogrify 版本不低于 2.1.0。测试 test_readers.py#L412-L494 覆盖了忽略过滤器与标签的完整行为。6.3 使用限制小结TYPOGRIFY默认关闭必须显式设为True破折号转换只作用于正文、标题、摘要三处元数据中的其他字段不受影响若未安装 typogrify 依赖开启TYPOGRIFY会在读取文章时抛出导入错误上述行为以当前仓库代码为准配置默认值见 pelican/settings.py#L151-L154文档定义见 docs/settings.rst#L306-L336。七、总结TYPOGRIFY_DASHES是 Pelican 排版体系中一个看似微小、实则精细的配置项。借助 article_with_typogrify_dashes.rst 这个 4 行夹具文件我们完整还原了它背后的完整链路RST/Markdown 双格式输入 → readers.py 中的 smartypantsset1/set2/set3装配 → test_readers.py 的逐字符断言。理解了三种模式的映射关系与 HTML 实体输出你就能够在不同写作习惯现代排版 vs 打字机传统之间自由切换让生成站点达到专业出版级的排版质感。【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址: https://gitcode.com/gh_mirrors/pe/pelican创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pelican 排版美化实战：深入解析 TYPOGRIFY_DASHES 与破折号处理机制
Pelican 排版美化实战深入解析 TYPOGRIFY_DASHES 与破折号处理机制【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址: https://gitcode.com/gh_mirrors/pe/pelican导读本文围绕 Pelican 测试夹具 article_with_typogrify_dashes.rst 展开讲解静态站点生成器 Pelican 中 Typogrify 排版增强功能的破折号处理原理。通过该夹具文件与 test_readers.py 中的断言测试你将完整掌握TYPOGRIFY_DASHES三种模式default/oldschool/oldschool_inverted对-、--、---连字符序列的 HTML 实体转换规则以及如何在pelicanconf.py中正确配置让生成的文章排版达到专业出版级水准。一、夹具文件一行标题里的排版玄机在 Pelican 仓库的 pelican/tests/content/ 目录下存在一个仅有 4 行的 RST 测试文件 article_with_typogrify_dashes.rstOne -, two --, three --- dashes! ################################ One: -; Two: --; Three: ---它不是一个普通的示例文章而是一个精心设计的测试夹具fixture第一行同时充当文章标题与元数据来源正文则通过三种连字符序列-、--、---来探测 Typogrify 在不同配置下的行为。与之对应仓库还提供了同名的 Markdown 版本 article_with_typogrify_dashes.md用于验证MdReader走的是同一条排版管道Title: One -, two --, three --- dashes! One: -; Two: --; Three: ---两个文件的核心差异在于标题的声明方式RST 用标题下划线####声明Markdown 用Title:元数据声明。而它们被设计为输出完全相同的渲染结果这正是测试的意图——无论你使用哪种内容格式破折号排版行为应当一致。二、背景Typogrify 是什么Pelican 如何接入Typogrify 是一套 Python 排版增强库它通过多个过滤器改善 HTML 的可读性主要包括smartypants把 ASCII 引号、连字符等替换为印刷级的智能引号与破折号en-dash–、em-dash—amp把裸规范为amp;caps为全大写缩写添加span classcaps样式initial_quotes处理段落开头的引号widont阻止标题/段落最后一行只剩一个单词避免孤行。在 Pelican 中Typogrify 属于可选依赖官方文档 docs/settings.rst 明确指出安装方式python -m pip install typogrify安装后在 pelicanconf.py 中开启开关即可。Pelican 的默认配置定义在 pelican/settings.pyTYPOGRIFY: False, TYPOGRIFY_IGNORE_TAGS: [], TYPOGRIFY_OMIT_FILTERS: [], TYPOGRIFY_DASHES: default,注意TYPOGRIFY默认是False这意味着默认构建不启用任何排版增强只有显式开启后破折号处理才会生效。三、TYPOGRIFY_DASHES三种破折号模式的完整对照TYPOGRIFY_DASHES控制 smartypants 过滤器如何解释多连字符序列。官方文档 docs/settings.rst 的说明可归纳为下表配置值单连字符-双连字符--三连字符---default保持为 hyphen-转为 em-dash—转为 em-dash hyphen— -oldschool保持为 hyphen-转为 en-dash–转为 em-dash—oldschool_inverted保持为 hyphen-转为 em-dash—转为 en-dash–用测试断言中的 HTML 实体表示#8211;即–#8212;即—nbsp;即不换行空格配置值输入-输入--输入---default-#8212;#8212;-oldschool-#8211;#8212;oldschool_inverted-#8212;#8211;三条规则的核心要点单连字符永远是连字符。无论哪种模式单个-都不会被转换因为它在英文排版中承担的是复合词连接符hyphen职能如 well-knowndefault不处理 en-dash。它只把双连字符折叠成 em-dash这也是 Typogrify/smartypants 最经典的行为对应 smartypants 内部的set1oldschool与oldschool_inverted是互逆的两套旧式映射。前者遵循传统打字机习惯--→en-dash---→em-dash后者则相反--→em-dash---→en-dash。3.1 从测试断言看三种模式的真实输出RST 版本对应的测试 test_readers.py#L588-L623 给出了精确的期望输出default 模式expected pOne: -; Two: #8212;; Three:nbsp;#8212;-/p\n expected_title One -, two #8212;, three #8212;-nbsp;dashes!正文中Two: --变为Two: #8212;em-dashThree: ---变为Three:nbsp;#8212;-em-dash hyphen标题中--- dashes变为#8212;-nbsp;dashes末尾单词前被插入了nbsp;——这是widont 过滤器在起作用防止标题最后一行只剩 dashes! 一个孤词。oldschool 模式expected pOne: -; Two: #8211;; Three:nbsp;#8212;/p\n expected_title One -, two #8211;, three #8212;nbsp;dashes!--转 en-dash#8211;---转 em-dash#8212;。oldschool_inverted 模式expected pOne: -; Two: #8212;; Three:nbsp;#8211;/p\n expected_title One -, two #8212;, three #8211;nbsp;dashes!--转 em-dash#8212;---转 en-dash#8211;与 oldschool 完全对调。Markdown 版本的测试位于 test_readers.py#L863-L898期望输出与 RST 版本逐字符一致唯一区别是 Markdown 渲染的段落末尾没有\n。这印证了两个格式在排版管道上是等价的。四、源码级原理readers.py 中的 smartypants 装配破折号转换发生在文章内容读取阶段。核心实现在 pelican/readers.py#L635-L680 的Readers.read_file()方法中执行顺序如下开关判断if self.settings[TYPOGRIFY]:才进入排版流程延迟导入import smartypants与from typogrify.filters import typogrify放在函数内部因为 typogrify 是可选依赖未安装时不应报错按配置选择映射集readers.py#L641-L647typogrify_dashes self.settings[TYPOGRIFY_DASHES] if typogrify_dashes oldschool: smartypants.Attr.default smartypants.Attr.set2 elif typogrify_dashes oldschool_inverted: smartypants.Attr.default smartypants.Attr.set3 else: smartypants.Attr.default smartypants.Attr.set1这里set1、set2、set3正是上一节三种模式的底层实现set1default把--折叠为 em-dash 且不产生 en-dashset2oldschool让--→en-dash、---→em-dashset3oldschool_inverted则反过来。兼容 Docutils 的引号处理readers.py#L649-L653代码额外设置smartypants.Attr.default | smartypants.Attr.w并附注释说明原因——DocutilsRST 渲染器在 smartypants 运行之前已经先把双引号替换成了quot;实体因此必须让 smartypants 也替换quot;才能正确生成智能引号作用范围readers.py#L673-L680排版过滤依次应用于content正文、metadata[title]标题、metadata[summary]摘要这也是测试中标题也会出现nbsp;与实体转换的原因。4.1 兼容性回退逻辑readers.py#L655-L671 中的typogrify_wrapper采用 try/except 链保证老版本 Typogrify 也能工作优先使用带TYPOGRIFY_IGNORE_TAGS和TYPOGRIFY_OMIT_FILTERS的完整签名若抛TypeError说明旧版不支持这些参数则降级为只传忽略标签再失败则只调用最基础的typogrify(text)。五、实战在 pelicanconf.py 中配置破折号风格启用并定制破折号处理只需在 pelicanconf.py或publishconf.py中加入如下配置# 启用 Typogrify 排版增强可选依赖需先安装python -m pip install typogrify TYPOGRIFY True # 破折号映射风格可选值 # default -- 双连字符转为 em-dash不产生 en-dash默认值 # oldschool -- 双连字符转为 en-dash三连字符转为 em-dash # oldschool_inverted -- 双连字符转为 em-dash三连字符转为 en-dash TYPOGRIFY_DASHES default # 可选跳过某些标签默认 Typogrify 会忽略 pre 与 code见下节 TYPOGRIFY_IGNORE_TAGS [] # 可选跳过某些过滤器允许值见下节 TYPOGRIFY_OMIT_FILTERS []配置后重新生成站点即可看到效果pelican content -s pelicanconf.py从源码结构可以推断TYPOGRIFY在 readers.py 中按文章逐篇生效因此任何新生成的 HTML 都会自动应用排版规则无需改动模板。六、相关配置项与使用限制6.1 TYPOGRIFY_IGNORE_TAGS官方文档 docs/settings.rst#L313-L317 说明这是一个让 Typogrify 忽略的标签列表。默认 Typogrify 会忽略pre和code标签以保护代码块不被引号/连字符转换破坏测试 test_readers.py#L496-L556 专门验证了这一点。默认值为[]即不额外忽略任何标签该特性要求 Typogrify 版本不低于 2.0.4。6.2 TYPOGRIFY_OMIT_FILTERS官方文档 docs/settings.rst#L319-L325 说明允许跳过的过滤器包括amp、smartypants、caps、initial_quotes、widont。例如若你只想保留破折号/引号转换而不想要孤行控制可设置TYPOGRIFY_OMIT_FILTERS [widont]默认值为[]应用全部过滤器该特性要求 Typogrify 版本不低于 2.1.0。测试 test_readers.py#L412-L494 覆盖了忽略过滤器与标签的完整行为。6.3 使用限制小结TYPOGRIFY默认关闭必须显式设为True破折号转换只作用于正文、标题、摘要三处元数据中的其他字段不受影响若未安装 typogrify 依赖开启TYPOGRIFY会在读取文章时抛出导入错误上述行为以当前仓库代码为准配置默认值见 pelican/settings.py#L151-L154文档定义见 docs/settings.rst#L306-L336。七、总结TYPOGRIFY_DASHES是 Pelican 排版体系中一个看似微小、实则精细的配置项。借助 article_with_typogrify_dashes.rst 这个 4 行夹具文件我们完整还原了它背后的完整链路RST/Markdown 双格式输入 → readers.py 中的 smartypantsset1/set2/set3装配 → test_readers.py 的逐字符断言。理解了三种模式的映射关系与 HTML 实体输出你就能够在不同写作习惯现代排版 vs 打字机传统之间自由切换让生成站点达到专业出版级的排版质感。【免费下载链接】pelicanStatic site generator that supports Markdown and reST syntax. Powered by Python.项目地址: https://gitcode.com/gh_mirrors/pe/pelican创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考