hexo的pandoc渲染器配置

1. hexo的渲染器简介

hexo的渲染器（render）负责将markdown转换为html代码，各大主题（theme）负责写css等来美化网页。

hexo默认使用的渲染器marked，对应的插件是hexo-renderer-marked
pandoc也可以将markdown转换为html，对应的插件是hexo-renderer-pandoc

因为marked对markdown的支持并不够好，pandoc更强大，为了博客的完美性，我选用了pandoc作为renderer。

只有知己知彼才能百战不殆，使用hexo-renderer-pandoc，就要对pandoc有所了解，知道各种设定，才能用最佳姿势书写博客。因此本文将介绍pandoc中关于markdown的一些设置，以及hexo-renderer-pandoc插件的部分设置。

2. hexo-renderer-pandoc的设置

首先区分一下，pandoc和hexo-renderer-pandoc：
pandoc是一个用haskell语言写的开源项目，可以在多种文本标记格式之间互相转换，包括markdown和html。
hexo-renderer-pandoc是hexo的一个插件，这个插件将接管hexo的渲染过程，调用pandoc执行渲染。

hexo渲染博客的流程是一个pipeline，hexo-renderer-pandoc就是其中一个环节，它的作用只有一个，调用pandoc.exe将markdown代码转换为html代码，然后将转换后的html代码送给流水线的下一个环节处理。hexo-renderer-pandoc默认调用的pandoc命令是：pandoc.exe -M pagetitle=dummy -f markdown-smart -t html-smart --mathjax，可见hexo-renderer-pandoc的作用就是给pandoc拼接参数。

在配置文件中，可以设置传递给pandoc的参数，修改_config.yml，你可以自定义pandoc的参数

pandoc:
  pandoc_path: /path/to/pandoc.exe
  args: ['-M', 'pagetitle=dummy', "-f", "markdown-smart", "-t", "html-smart", "--mathjax"]

除了直接写明所有参数，还有一种将被废弃的写法

pandoc:
  pandoc_path: /path/to/pandoc.exe
  extensions: []
  filters: []
  extra: []

分别指定extensions、filters以及额外的参数

3. pandoc的参数

本节将介绍pandoc的一些参数，以下内容均来自本人研读pandoc的文档：https://pandoc.org/MANUAL.html

术语约定： pandoc提供了丰富的extension，下文“拓展、扩展、插件”均指extension

pandoc的命令格式为：

C:\blog>pandoc --help
pandoc [OPTIONS] [FILES]
  -f FORMAT, -r FORMAT  --from=FORMAT, --read=FORMAT
  -t FORMAT, -w FORMAT  --to=FORMAT, --write=FORMAT
...

pandoc提供了丰富的扩展，各种语法的启用/禁用都通过扩展来实现

FORMAT的格式为<format>[<+|-><extension>...]

通过在FORMAT插件前写+/-来启用/禁用各种扩展（extension），比如-f markdown-smart就在输入是markdown的基础上禁用了smart扩展。

pandoc内置支持以下markdown格式： - markdown_strict 最基本、严格的markdown语法 - markdown 这是Pandoc's Markdown, 扩展了部分语法 - markdown_github 这是GitHub支持的markdown语法
还有一些markdown格式，由于不常用，在此不列出。

不同模式默认启用的插件

markdown_strict默认启用的插件：

+raw_html
+shortcut_reference_links
+spaced_reference_links

markdown默认启用的插件

+all_symbols_escapable
+auto_identifiers
+backtick_code_blocks
+blank_before_blockquote
+blank_before_header
+bracketed_spans
+citations
+definition_lists
+escaped_line_breaks
+example_lists
+fancy_lists
+fenced_code_attributes
+fenced_code_blocks
+fenced_divs
+footnotes
+grid_tables
+header_attributes
+implicit_figures
+implicit_header_references
+inline_code_attributes
+inline_notes
+intraword_underscores
+latex_macros
+line_blocks
+link_attributes
+markdown_in_html_blocks
+multiline_tables
+native_divs
+native_spans
+pandoc_title_block
+pipe_tables
+raw_attribute
+raw_html
+raw_tex
+shortcut_reference_links
+simple_tables
+smart
+space_in_atx_header
+startnum
+strikeout
+subscript
+superscript
+task_lists
+table_captions
+tex_math_dollars
+yaml_metadata_block

Pandoc's markdown格式固然好，但是有部分语法我并不喜欢，所以需要禁用相关扩展。markdown_strict虽然禁用了大部分扩展，但是也导致部分好用的语法失效，因此，我根据自己的习惯深度定制了扩展的启用/禁用。

接下来将建议Pandoc's markdown格式下一些建议禁用/启用的插件。

建议的设置：

pandoc:
  args: ['-f', 'markdown-smart+autolink_bare_uris+gfm_auto_identifiers-blank_before_blockquote-blank_before_header', '-t', 'html-smart', '--mathjax']

+gfm_auto_identifiers：修改identifier的格式，这种格式和博客园支持的格式相同，保证和博客园的兼容性。identifier是给标题生成的唯一标识符，用于建立针对具体段落超链接。

-blank_before_blockquote：该插件要求 一个引用（>）段落 之前必须有空行。

-blank_before_header：该插件要求 一个标题（# xxx）之前必须有空行。

-autolink_bare_uris：即使不被尖括号<...>包围，也使所有绝对的URI都转为链接。 该插件将把URL渲染为为可点击的超链接，即直接写https://....，就会渲染为链接。若关闭，则需要写[xxx](https://....)或者<https://...>。但是该插件的坏处是：会错误地识别@符号，比如写个a@b，都会渲染为mailto:a@b