企业官网建设流程全解析

• 移动开发

<output_article>

基于 Markor 的 Jekyll 博客写作指南：从模板文件到 Front Matter 渲染机制

导读

本文以 Markor 内置模板 app/src/main/assets/templates/jekyll-post.md 为切入点，系统讲解在 Android 设备上使用 Markor 编写 Jekyll 博客文章的完整工作流：从模板中的 YAML Front Matter（前置元数据）字段含义、Markor 内置的 Jekyll 语法扩展，到新建文件时的模板加载与占位符替换机制。读完本文，你将掌握如何在 Markor 中直接产出符合 Jekyll 规范、可直接推送至 GitHub Pages 等静态站点的 Markdown 博文，并能理解预览模式下 Front Matter 被解析和渲染的底层原理。

一、模板全貌：一份为 Jekyll 预置的 Markdown 博文骨架

Markor 在应用内置资产目录assets/templates下随包分发了一批文档模板（AppSettings.java 中的getBuiltinTemplates()通过AssetManager.list("templates")枚举并读取该目录下的全部文件），其中 jekyll-post.md 专为 Jekyll 静态博客定制。模板完整内容如下：

--- layout: post tags: [] categories: [] #date: 2019-06-25 13:14:15 #excerpt: '' #image: 'BASEURL/assets/blog/img/.png' #description: #permalink: title: 'title' ---

可以看到，这是一份"形简意丰"的骨架：正文区为空，真正有价值的是文件顶部的 YAML Front Matter 块。它与 Jekyll 官方对博文文件的要求完全对齐——Jekyll 要求每篇文章在文件开头用---包裹的 YAML 块声明元数据，Markor 恰好把这一步做成了开箱即用的模板。

值得注意的是，仓库中还存在同主题的 AsciiDoc 版本 app/src/main/assets/templates/jekyll-post.adoc，以及用于演示的实际示例文件 samples/2029-01-01-jekyll-post.md、samples/2029-01-01-jekyll-post.adoc。示例文件名带2029-01-01日期前缀，正是 Jekyll 标准的文章命名约定（见本文第五节）。

二、Front Matter 字段逐项解析

模板中的每一行字段都有明确的 Jekyll 语义，下面逐一说明其作用、取值方式与在 Markor 中的表现。

2.1 布局与标题（必填核心字段）

其中title建议保留单引号包裹——Jekyll 的 YAML 解析器（基于 Ruby）对未加引号、含特殊字符的字符串容易误解析，引号是安全写法。

2.2 标签与分类（内容组织字段）

tags: [] categories: []

两个字段默认是空数组，但取值方式不同：

• tags：文章标签，可写为[markdown, android]或 YAML 列表形式：

  tags: - markdown - android

  在 Markor 的预览渲染中，tags会被特殊处理：源码 MarkdownTextConverter.java 中有一条专门的分支——当tags恰好只有一个元素且形如"[tag1,tag2,tag3]"时，会先按逗号拆分、再通过LinkedHashSet去重保序，最终展开为独立的标签项；同时模板的 CSS（CSS_FRONTMATTER）会为标签渲染圆角胶囊样式。

• categories：文章分类，Jekyll 用它生成分类归档页，支持层级结构（如[tech, android]）。

2.3 被注释的可选字段（按需启用）

模板用#注释保留了四个常用可选字段，取消注释即可启用：

这种"默认必填字段开启、可选字段注释保留"的设计，让模板既能开箱即用，又保留了完整的扩展空间。

三、Markor 如何解析与渲染 Jekyll 语法

模板之所以能无缝工作，是因为 Markor 的 Markdown 转换器在底层集成了对 Jekyll 语法的完整支持。证据集中在 MarkdownTextConverter.java：

3.1 解析器扩展注册

转换器基于 flexmark-java 构建，在flexmarkExtensions列表中显式注册了与 Jekyll 直接相关的三个扩展（源码 L126-L147）：

JekyllTagExtension.create(), // 识别 {% ... %} 标签语法 JekyllFrontMatterExtension.create(), // 识别 --- 包裹的 Front Matter 块 YamlFrontMatterExtension.create(), // 将 Front Matter 解析为结构化 YAML

这意味着：即使没有开启任何额外选项，Markor 在预览模式中也能正确把---之间的 YAML 块从正文中剥离出来解析，而不会把它误当作水平分割线或正文文本。

3.2 Front Matter 的可视化渲染

Markor 默认不会把 Front Matter 原样显示在预览中，而是按需渲染成结构化信息条。其逻辑位于 MarkdownTextConverter.java L216-L241：

1. 只有当文档以---开头，且满足以下任一条件时才触发解析：
   • 用户在设置中配置了要显示的 YAML 键（AppSettings.getMarkdownShownYamlFrontMatterKeys()）；
   • 正文中出现了{{ post.xxx }}形式的令牌（YAML_FRONTMATTER_TOKEN_PATTERN正则匹配）。
2. 通过extractYamlAttributes()用YamlFrontMatterExtension单独解析，得到Map<String, List<String>>形式的键值对。
3. 仅渲染白名单内的属性，每个属性包装为front-matter-item容器，整体放入.front-matter-container，并注入CSS_FRONTMARTTER样式——这就是预览中顶部那条"标题、标签胶囊、描述"信息条的来源。

3.3 正文内的{{ post.xxx }}令牌替换

这是模板与 Markor 交互最巧妙的一环。在 Jekyll 站点中，正文可以使用{{ page.title }}、{{ page.tags }}等 Liquid 变量；Markor 在本地预览时无法运行 Jekyll，于是实现了近似机制：源码 replaceTokens() 会扫描正文中的{{ post.<attr> }}令牌，并把对应 YAML 属性的值（经过去引号、HTML 转义、--→–破折号处理）回填进去，最终渲染为高亮的post-item-<attr>标签。

例如，若 Front Matter 中声明了tags: [markdown, android]，正文某处写入：

本文标签：{{ post.tags }}

预览时会自动显示为两个独立的标签条目。这让你在手机上写作时，就能即时看到标签、标题等元数据最终会以什么形态出现在页面上。

3.4 Jekyll Liquid 令牌的本地化替代

模板注释与正文中可能出现{{ site.time | date: '%x' }}、{{ site.baseurl }}这类 Liquid 表达式。Markor 在转换时做了两处替换（MarkdownTextConverter.java L299-L300）：

markup = markup.replace("{{ site.baseurl }}", "..") .replace(TOKEN_SITE_DATE_JEKYLL, TOKEN_POST_TODAY_DATE);

• {{ site.baseurl }}被替换为..——因为 Markor 中 Jekyll 文章通常存放在_posts目录，该目录相对于站点根目录恰好上跳一级，图片等资源引用（如![](../assets/img/x.png)）因此可正确解析；
• {{ site.time | date: '%x' }}被替换为{{ post.date_today }}，后者在 TextConverterBase.java 中最终被替换为设备当前的本地化日期字符串。

这套机制让 Markor 的预览与 Jekyll 站点的最终渲染保持一致：本地所见，即线上所得。

四、在 Markor 中使用模板新建博文

模板的消费入口是"新建文件"对话框，对应源码 NewFileDialog.java。

4.1 模板加载流程

NewFileDialog.java L156-L162 将三部分来源合并进模板下拉框：

1. 第一项固定为"空文件"（R.string.empty_file）；
2. 接着是用户在设置中配置的 snippets 目录下的所有纯文本片段文件（getSnippetFiles()）；
3. 最后是内置模板（getBuiltinTemplates()），即assets/templates下的全部文件——jekyll-post.md就在这里。

4.2 文件名自动生成

选中jekyll-post.md模板后：

• 对话框会用模板文件名自动建议标题与扩展名：jekyll-post+.md（NewFileDialog.java L173-L188）；
• 标题格式可通过格式输入框定制（支持{{title}}占位符与yyyy-MM-dd'T'HHmmss等日期格式，默认规则见 NewFileDialog.java L244-L257）；
• 确认后，模板内容作为新文件内容写入，模板名与格式偏好会被记住，下次新建同类型文件时自动预选（NewFileDialog.java L311-L315）。

4.3 与 AsciiDoc 模板的对照

若你的博客使用 AsciiDoc（Jekyll 同样支持），可对照参考 jekyll-post.adoc：它以= My Title起头，用:page-subtitle:、:page-tags:、:page-last-updated:等文档属性承载元数据，并通过ifndef::env-site[]条件块实现"本地预览显示副标题、线上 Jekyll 站点不重复显示"的差异化渲染。两份模板体现了 Markor 对 Markdown / AsciiDoc 双格式 Jekyll 工作流的完整覆盖。

五、写作到发布的完整流程

结合模板与 Markor 的功能，一条完整的移动端 Jekyll 写作链路如下：

1. 新建文件：打开"新建文件"对话框，模板选择jekyll-post.md，标题格式可设置为 Jekyll 规范的yyyy-MM-dd-{{title}}（日期前缀便于 Jekyll 识别发布时间）。
2. 填写元数据：把title: 'title'替换为真实标题；按需填写tags、categories，取消注释date、excerpt、permalink等可选字段。
3. 写作正文：利用 Markor 的 Markdown 全语法支持（任务列表、表格、脚注、数学公式 KaTeX、Mermaid 图表等，均由 MarkdownTextConverter.java 注册的 flexmark 扩展提供）；需要展示元数据时，在正文中写{{ post.tags }}等令牌。
4. 本地预览：切换预览模式，Front Matter 会渲染为信息条，{{ site.baseurl }}与日期令牌被替换为本地可解析值，图片路径经escapeSpacesInLink()处理（空格转%20，见 MarkdownTextConverter.java L349-L376）。
5. 归档发布：将文件放入 Jekyll 仓库的_posts目录（Markor 检测到_posts/blog/post文件夹时还会自动为预览注入目录 TOC，见 MarkdownTextConverter.java L244-L259），经 Git 推送后由 Jekyll 构建发布。

值得强调的是，模板中注释字段与文件命名都遵循 Jekyll 官方约定（YYYY-MM-DD-title.ext、---定界符、layout必填），因此只要不删改 Front Matter 结构，Markor 产出的文件即可直接进入 Jekyll 构建流水线，无需二次编辑。

六、小结

jekyll-post.md虽仅十余行，却是 Markor 面向 Jekyll 博客场景的核心载体：它既是可复制的写作骨架，又是测试 Markor Jekyll 语法支持的天然样例。配合 MarkdownTextConverter.java 中的 Jekyll 扩展注册、Front Matter 白名单渲染与令牌替换机制，以及 NewFileDialog.java 的模板加载流程，你完全可以在手机端完成"建文件—填元数据—写作—预览—归档"的 Jekyll 博客全流程，且预览结果与线上渲染保持一致。 </output_article>

• 移动开发