使用Jekyll撰写博客(一)

一个基于Jekyll网站的目录结构一般是这样的:

.
├── _config.yml 
├── _drafts
|   ├── begin-with-the-crazy-ideas.textile
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
|   └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
├── .jekyll-metadata
└── index.html
  1. _config.yml`

    保存配置数据。很多配置选项都可以直接在命令行中进行设置,但是如果你把那些配置写在这儿,你就不用非要去记住那些命令了。

  2. _drafts

    drafts(草稿)是未发布的文章。这些文件的格式中都没有 title.MARKUP 数据。

  3. _includes

    你可以加载这些包含部分到你的布局或者文章中以方便重用。可以用这个标签 {% include file.ext %}来把文件 _includes/file.ext 包含进来。

  4. _layouts

    layouts(布局)是包裹在文章外部的模板。布局可以在 YAML 头信息中根据不同文章进行选择。这将在下一个部分进行介绍。标签{{ content }}可以将content插入页面中。

  5. _posts

    这里放的就是你的文章了。文件格式很重要,必须要符合:YEAR-MONTH-DAY-title.MARKUP。 永久链接可以在文章中自己定制,但是数据和标记语言都是根据文件名来确定的。

  6. _data

    格式化好的网站数据应放在这里。jekyll 的引擎会自动加载在该目录下所有的 yaml 文件(后缀是 .yml, .yaml, .json 或者 .csv )。这些文件可以经由 `site.data` 访问。如果有一个 members.yml 文件在该目录下,你就可以通过 site.data.members 获取该文件的内容。

  7. _site

    一旦 Jekyll 完成转换,就会将生成的页面放在这里(默认)。最好将这个目录放进你的 .gitignore 文件中。

  8. .jekyll-metadata

    该文件帮助 Jekyll 跟踪哪些文件从上次建立站点开始到现在没有被修改,哪些文件需要在下一次站点建立时重新生成。该文件不会被包含在生成的站点中。将它加入到你的 .gitignore 文件可能是一个好注意。

  9. index.html and other HTML, Markdown, Textile files

    如果这些文件中包含YAML 头信息部分,Jekyll 就会自动将它们进行转换。当然,其他的如 .html, .markdown, .md, 或者 .textile 等在你的站点根目录下或者不是以上提到的目录中的文件也会被转换。

  10. Other Files/Folders

其他一些未被提及的目录和文件如css 还有 images 文件夹,favicon.ico 等文件都将被完全拷贝到生成的 site 中。

预定义的全局变量

  1. layout

    如果设置的话,会指定使用该模板文件。指定模板文件时候不需要文件扩展名。模板文件必须放在 _layouts 目录下。

  2. permalink

    如果你需要让你发布的博客的 URL 地址不同于默认值 /year/month/day/title.html,那你就设置这个变量,然后变量值就会作为最终的 URL 地址。

  3. published

    如果你不想在站点生成后展示某篇特定的博文,那么就设置(该博文的)该变量为 false

  4. category,categories

除了将博客文章放在某个文件夹下面外,你还可以指定博客的一个或者多个分类属性。这样当你的站点生成后,这些文章就可以根据这些分类来阅读。categories 可以通过 YAML list,或者以空格隔开指定。

  1. tags

类似分类 categories,一篇文章也可以给它增加一个或者多个标签。同样,tags 可以通过 YAML 列表或者以空格隔开指定。

文章中预定义的变量

文章中可以使用这些在头信息列表中未包含的变量

  1. date

    这里的日期会覆盖文章名字中的日期。这样就可以用来保障文章排序的正确。日期的具体格式为YYYY-MM-DD HH:MM:SS +/-TTTT;时,分,秒和时区都是可选的。

撰写博客

每篇文章必须要有YAML头信息,如果没有,则不会被解析

创建文章

所有的文章都在_posts文件夹中。Jekyll 要求一篇文章的文件名遵循下面的格式:

YYYY-MM-DD-标题.MARKUP

引用图片和其他资源

一种常用的做法是在工程的根目录下创建一个文件夹,命名为asserts或者downloads或其它名字也可以,将图片文件,下载文件或者其它的资源放到这个文件夹下(这些文件夹会自动被拷贝到_site中)。然后在任何一篇文章中,它们都可以用站点的根目录来进行引用。

使用site.url变量:{{ site.url }}

ps:如果你确定你站点只在域名的根URL下展示,那么可以不使用{{ site.url }}变量,在这种情况下,直接使用/path/file.jpg即可。

文章的目录

Liquid 模版语言和它的标记,下面是如何创建文章列表的简单例子:

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

了解Jekyll 的模版是怎样工作的

请注意,post 变量仅在 for 循环中存在。如果你希望使用当前呈现的页面/博文中的变量(在 for 循环中的博文/页面的变量),请使用 page 变量来替代它。

文章摘要

Jekyll 会自动取每篇文章从开头到第一次出现 excerpt_separator 的地方作为文章的摘要,并将此内容保存到变量 post.excerpt 中。拿上面生成文章列表的例子,你可能想在每个标题下给出文章内容的提示,你可以在每篇文章的第一段加上如下的代码:

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

由于 Jekyll 会提取第一段的内容,你没有必要将摘要包裹在 p 标签中,它已经为你做了这项工作。如果你希望移除它们可以使用如下的代码:

{{ post.excerpt | remove: '<p>' | remove: '</p>' }}

如果你不喜欢自动生成摘要,你可以在文章的 YAML 头信息中增加 excerpt 来覆盖它。另外,你也可以选择在文章中自定义一个 excerpt_separator:

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

Excerpt
<!--more-->
Out-of-excerpt

你也可以在 _config.yml 中全局声明 excerpt_separator

完全禁止掉可以将 excerpt_separator 设置成 ""

同时,对于由 Liquid 标签输出的内容,你可以通过| strip_html过滤器来移除输出内容中的html标签。这在某些场景,如在你博文的head中生成

meta="description",以及其他html标签与内容不应混杂的场景下很有帮助。

高亮代码片段

{% highlight ruby %}
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end
{% endhighlight %}

如果显示行数,在代码片段中添加关键字linenos

补充

  1. Minima at GitHub: jekyll / minima

    安装Jekyll,并执行jukyll new blog后,里面的site默认使用的是minima主题,查看_config.yml文件:

    主题中包含的文件夹及文件有(有些可能不会在site中显示出来,但确实存在,具体请参考jekyll搭建章节的补充内容):

    1. _layouts

      • default.html — The base layout that lays the foundation for subsequent layouts. The derived layouts inject their contents into this file at the line that says {{ content }} and are linked to this file via FrontMatter declaration layout: default.
      • home.html — The layout for your landing-page / home-page / index-page.
      • page.html— The layout for your documents that contain FrontMatter, but are not posts.
      • post.html — The layout for your posts.
    2. _includes

      • disqus_comments.html — Code to markup disqus comment box.
      • footer.html — Defines the site’s footer section.
      • google-analytics.html — Inserts Google Analytics module (active only in production environment).
      • head.html — Code-block that defines the <head></head> in default layout.
      • header.html — Defines the site’s main header section. By default, pages with a defined title attribute will have links displayed here.
      • icon-* files — Inserts github and twitter ids with respective icons.
  2. 解决代码冲突问题

    临时禁止执行 Jekyll Tag 命令,在生成的内容里存在冲突的语法片段的情况(如果我们想把一段Liquid代码片段作为文章内容)下很有用。

   {% raw % }
     In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
   {% endraw % }

参考Jekyll/Liquid API 语法文档

本页添加评论功能(via disqus)

根据 jekyll / minima可以知道,我们此时搭建的site默认使用的minima主题,查看该页面的内容:

这一部分提示我们可以使用(Disqus)为文章添加评论功能。

那就一步步的按照该部分做(下面是先完成为某一个页面添加评论的功能):

  1. 在该页面的 YAML Front Matter 添加下面内容:

    comments: true
    

    如果不想使某一个post显示评论功能,那么可以将comments: false

    在根目录的_config.yml文件中添加下面的内容(使用空格代替Tab键):

    disqus:
        shortname: my_disqus_shortname
    

    没有my_disqus_shortname?,点击上面的here:

    里面的文章可以读一读,有助于对disqus的理解。

  2. 注册:

    register your site,在这里我使用的是Google帐号登录

    后面根据上面的指引一步步的填写就可以了,只是有一点需要注意,就是在填写Website URL时,不能加上“www.”,例如我的域名是atyouyou.com,那么在填写时就填入http://atyouyou.com

    ![](http://localhost:4000/images/2017-12-17_153428.png)
    
  3. 安装:

    后面将下面的代码直接粘贴复制到博文的最下面,就可以了。

    ps:教程中有一句话:

    Comments are enabled by default and will only appear in production, i.e., JEKYLL_ENV=production

    理解应该是评论的功能在默认情况下是开启的,至于需要处于Jekyll的生产环境中,指的是jekyll.environment == "production"(参考搭建Jekyll章节的补充内容)。

  4. 效果图:

    如本篇显示效果。

    此处只是显示出了效果,是一个不错的开端。细节问题,需参照官方站点。后面,可以将评论部分加入到模板中。

    后来经过测试,好吧!如果没有出现还可能是因为…GFW,不过如果你的页面显示像这样:

    则也表示成功,评论功能已经正常使用了…