Improve this page

文章 Posts

Jekyll 内置了博客功能。你只需要把博客文章写成文本文件，Jekyll 会帮你把它们变成一个完整的博客网站。

_posts 文件夹

_posts 文件夹就是你放博客文章的地方。你通常会使用 Markdown 来写文章，也可以用 HTML。

创建文章

要创建一篇文章，只需要在你的 _posts 目录下添加一个符合下面格式的文件：

YEAR-MONTH-DAY-title.MARKUP

其中 YEAR 是四位数年份，MONTH 和 DAY 是两位数的月份和日期，MARKUP 是文件格式的扩展名。例如，以下是几个合法的文章文件名：

2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.md

所有博客文章文件都必须以 front matter（前置数据）开始，通常用来设置一个 layout（布局）或其他元数据。最简单的 front matter 可以是空的，比如：

---
layout: post
title:  "欢迎来到 JekyllDo!"
---

# 你好

**Hello world**，这是我第一篇 Jekyll Do 博客文章。

希望你喜欢！
小技巧™：链接到其他文章

使用 post_url 标签来链接其他文章，这样在站点的链接样式（permalink）变化时也不会出错。

注意字符编码

一些内容处理器可能会把某些字符自动转换为更漂亮的样式。 比如 Redcarpet 中的 smart 扩展会把标准的 ASCII 引号变成卷曲的 Unicode 引号。 为了让浏览器正确显示这些字符，你需要在布局的 <head> 中添加 <meta charset="utf-8"> 来指定字符集。

插入图片和资源

在写博客的过程中，你可能会想要插入图片、下载链接，或者其他数字资源。一种常见的做法是在项目目录的根目录下创建一个叫 assets 的文件夹，把所有图片、文件或者其他资源都放进去。然后你就可以在文章中通过站点的根路径来引用这些资源。最佳做法取决于你的网站域名或子路径的设置，但下面是几个使用 Markdown 的简单例子：

在文章中插入一张图片：

... 如下图所示：
![My helpful screenshot](/assets/screenshot.jpg)

为读者提供 PDF 下载链接：

... 你可以[下载 PDF](/assets/mydoc.pdf)。

显示文章列表索引

借助 Liquid 模板语言和它的标签语法，在其他页面上显示文章索引是很容易的。下面是一个简单的例子，用来生成你博客文章的链接列表：

<ul>
  {% for post in site.posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
</ul>

你可以完全自由地控制你的文章展示方式和位置，以及你的网站结构。如果你想更深入了解，可以阅读更多关于 Jekyll 中 模板的使用方法。

注意，上面代码中的 post 变量只在 for 循环内部可用。如果你想访问当前正在渲染的页面或文章的变量（也就是包含 for 循环的那个页面或文章的变量），你需要使用 page 变量。

标签与分类

Jekyll 在博客文章中对 标签（tags）和 分类（categories）提供了原生支持。

标签

你可以在文章的 front matter 中使用 tag（单个标签）或 tags（多个标签）来定义标签。
由于 Jekyll 会默认将 tags 映射为一个数组，如果你写的是一个带空格的字符串，它会自动 拆分 成多个标签。例如：

  • 使用 tag: classic hollywood 时，会被当成一个整体标签 "classic hollywood"。
  • 使用 tags: classic hollywood 时，会被拆分成两个标签 ["classic", "hollywood"]。

不管你用的是 tag 还是 tags，Jekyll 都会把数据保存为 tags 这个复数形式，并暴露给 Liquid 模板使用。

站点中所有注册的标签都可以通过 site.tags 在模板中访问。对 site.tags 进行循环会得到一个包含两个元素的数组，其中第一个元素是标签名，第二个是拥有该标签的文章列表。

{% for tag in site.tags %}
  <h3>{{ tag[0] }}</h3>
  <ul>
    {% for post in tag[1] %}
      <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
{% endfor %}

分类

文章的分类和标签的用法类似：

  • 可以在 front matter 中通过 category 或 categories 来定义（使用方式和 tag、tags 一样）
  • 所有在站点中注册的分类都可以通过 site.categories 在模板中访问，并像标签一样进行循环操作

不过分类和标签的相似之处仅止于此。

和标签不同，分类还可以通过文章的文件路径自动生成。如果某篇文章的路径是：

movies/horror/_posts/2019-05-21-bride-of-chucky.markdown

那么 movies 和 horror 就会被自动识别为该文章的分类。

如果文章同时在 front matter 中定义了分类，而这些分类不在路径中，那它们也会被加入到分类列表中。

分类和标签最大的不同在于：分类可以出现在文章生成后的 URL 中，而标签不会。

因此，如果 front matter 写的是：

  • category: classic hollywood，那么文章的地址就是：movies/horror/classic%20hollywood/2019/05/21/bride-of-chucky.html

  • 而如果是 categories: classic hollywood，则地址会变为：movies/horror/classic/hollywood/2019/05/21/bride-of-chucky.html

文章摘要

你可以通过在文章对象上使用 excerpt 变量来获取文章内容的简要片段。默认情况下，这段摘要是文章中的第一个段落。不过你也可以通过在 front matter 或 _config.yml 中设置 excerpt_separator（摘要分隔符）变量来自定义。

---
excerpt_separator: <!--more-->
---

带多段内容的摘要

这是摘要中的另一段内容。
<!--more-->
这段内容不属于摘要

以下是一个输出文章列表并显示摘要的例子：

<ul>
  {% for post in site.posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
      {{ post.excerpt }}
    </li>
  {% endfor %}
</ul>

草稿

草稿是指文件名中没有日期的文章。这些文章通常是你还在写的内容，不打算立刻发布。要使用草稿功能，你需要在站点根目录下创建一个 _drafts 文件夹，并在其中创建你的第一个草稿：

.
├── _drafts
│   └── a-draft-post.md
...

要预览包含草稿的站点，请在运行 jekyll serve 或 jekyll build 命令时加上 --drafts 参数。每篇草稿会自动使用该文件的最后修改时间作为发布日期，因此你当前正在编辑的草稿会显示为最新的文章。