撰写内容

• 通用
  • 文件格式
  • YAML 头部
• 文章（Post）
  • 支持的 YAML 元信息
  • 划分预览部分
• 自定义页面（Page）
  • 页面访问逻辑
  • 支持的 YAML 元信息
• 页面部件（Widget）
  • 支持的 YAML 元信息

VeriPress 支持三种内容形式：文章（post）、自定义页面（page）、页面部件（widget）。其中，文章（post）是指可以通过 /post/<year>/<month>/<day>/<post_name>/ 形式的 URL 访问的页面；自定义页面（page）是指直接在根 URL 后加上页面路径来访问的页面，如 /hello/ 或 /my-custom/page.html；页面部件（widget）是指常驻页面的小部件，需要主题支持，默认主题只支持一种部件，也就是侧边栏部件。

通用

文件格式

除了之前的 开始使用 中提到的 Markdown 格式，目前还支持 TXT 格式，后续还会加入其它格式的支持。VeriPress 通过文件扩展名来区分格式，并通过相应格式的解析器将正文解析成 HTML 并传给主题来显示。下面是目前支持的格式列表：

其中，Markdown 格式采用「Markdown Extra」扩展，该扩展在 标准 Markdown 语法 的基础上，加入了一些其它实用语法，具体见 PHP Markdown Extra。

无论使用什么格式书写内容，文件的开头都使用 YAML 来标记元信息，并在其上下分别用 --- 来分隔，例如：

---
title: 文章的标题
author: 作者
---

正文内容，可使用不同的格式／标记语言书写。

YAML 头部

YAML 头部用于标记文章、页面、部件的一些基本元信息，比如标题、作者、标签、分类等，这里的元信息将被传到主题的模板文件中，因此具体这些信息有哪些被显示出来、以什么形式显示，都取决于你使用的主题，后面对三种内容形式的分别阐述中，将主要给出 VeriPress 原生支持的（或者说默认主题支持的）元信息项。

另外，三种内容形式都支持的一个元信息是 is_draft，用于表示该篇内容是否为草稿，例如，如果有一篇文章内容如下：

---
title: 标题
is_draft: true
---

正文内容

则它将不会显示在文章列表中，也无法通过具体路径访问（API 也无法访问）。is_draft 的默认值是 false，因此如果不填，默认认为不是草稿，会将其发布。这个元信息的效果是由 VeriPress 核心程序所保证的，因此不会受主题的影响。

另外，所有官方主题（即 veripress/themes 仓库中的主题），均支持 language 元信息（三种内容形式都支持），此元信息项的值，会覆盖 site.json 中的同名项，见 修改网站信息。

文章（Post）

文章可通过形如 /post/<year>/<month>/<day>/<post_name>/ 的 URL 访问，文件放在 posts 目录中，命名格式形如 2017-03-20-post-name.md，因为文章其实就是博客的「博文」，发布时间非常重要，因此在文件名中指出创建日期将有助于管理，同时也在 YAML 头部没有指定创建日期时作为默认的创建日期。

支持的 YAML 元信息

文章默认支持的 YAML 元信息如下：

划分预览部分

文章还支持在正文中划分预览部分，从而在文章列表中仅显示预览部分，以节省页面空间。不同的文件格式，使用不同的预览分隔标记（或称阅读更多标记），如下：

预览分隔标记之前的内容将被作为预览部分显示在首页文章列表中（需要主题支持），并显示一个 READ MORE 链接，而没有预览分隔标记的文章将默认把全部正文作为预览部分，这时将不显示 READ MORE 链接（这是默认主题的行为，第三方主题未必这样）。

注意：分隔标记前后都需要换行才有效。

自定义页面（Page）

自定义页面有时候被直接称为「页面」，它们可通过形如 /hello/ 或 /my-custom/page.html 的 URL 访问，文件放在 pages 目录中，命名格式形如 page-name.md。

页面访问逻辑

之所以称为自定义页面，是因为这种内容形式自定义性比较强，你可以在 pages 中创建多级目录来组织自定义页面，甚至可以直接将 HTML 文件或其它静态文件放在里面。

对于使用非 HTML、且 VeriPress 支持的文件格式，可以通过 .html 后缀的 URL 来访问，比如有一个自定义页面的文件路径是 /pages/a/b/c/d.md，你将可以通过 /a/b/c/d.html 来访问这个页面，与此同时，你还可以直接通过 /a/b/c/d.md 来访问这个原始 Markdown 文件（前提是配置文件中的 PAGE_SOURCE_ACCESSIBLE 设置为 True，见 配置文件）。如果这里的 Markdown 文件名是 index，例如 /pages/a/b/c/index.md，你还可以通过 /a/b/c/ 来访问。

而如果直接使用 HTML 文件，逻辑则更加简单：只要这个文件存在，就会直接返回，例如你可以通过 URL /abc/index.html 或 /abc/ 来访问文件 /pages/abc/index.html。

如果你直接在 pages 目录中创建了一个 index.md 或 index.html 或其它所支持的文件格式，这个自定义页面将会覆盖首页，也就是当你访问 URL / 的时候，访问的实际上是这个自定义页面，而不是默认的文章列表。

支持的 YAML 元信息

自定义页面默认支持的 YAML 元信息如下：

页面部件（Widget）

页面部件是指常驻页面的小部件，例如出现在侧边栏、顶栏、footer 等，但这需要主题支持，默认主题只支持侧边栏部件（sidebar）。

支持的 YAML 元信息

页面部件默认支持的 YAML 元信息如下：

对于页面部件来说，上面两个元信息基本上都是必填（除非显示顺序不重要或主题不区分位置）。