注:由于本人换用别的生成引擎,因此,此文不再更新,不足部分请参考其他文章。

定制日志系统:jekyll

两种方式:

  1. 利用github的自动生成:settings——》Automatic Page Generator——》Continue To Layouts——》选择系统提供的模板——》发布。 之后生成一个叫gh-pages仓库,里面是生成的html文件。
  2. 利用jekyll定制,或者是别的静态站点生成工具定制

下面使用jekyll来生成静态站,所需软件:ruby gem

简单安装过程:

gem install jekyll
cd 本地想存放站点文件夹的上级文件夹
~/.gem/ruby/2.1.0/bin/jekyll new 站点文件夹
cd 站点文件夹
jekyll serve
# => 浏览器中查看 http://localhost:4000

查看文件夹,结构如下:

文件夹名/
├── _config.yml
├── _includes
│   ├── footer.html
│   ├── head.html
│   └── header.html
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── _posts
│   └── 2014-08-06-welcome-to-jekyll.markdown
├── css
│   └── main.css
├── feed.xml
├── about.md
└── index.html

说明:

想存放静态文件,比如图片,css,js等,可以自己新建一个文件夹,比如名为: static

注意:由于ruby2 的路径编码问题,jekyll上面的文件名不要用中文,会导致出现编码问题,jekyll站点文件里面可以utf-8。

测试效果:

本地写markdown文件,放入 _post 文件夹中,如果想测试下效果,可以本地使用jekyll生成,然后在浏览器中查看。

jekyll build
# => 当前文件夹将生成到 ./_site

问题:如何递增生成?可结合git的对比功能实现。

定制页面模板:

jekyll把 _layouts 目录中的文档看做是生成用的模板,如果某个文档中的头部变量声明中指定了layout,则Jekyll在生成页面时会使用该模板进行渲染,用文档的内容替换模板中的部分。模板之间可相互嵌套调用:

---
layout: post
...
---

利用好Liquid语言的include语法能够带来很大的变量。被包含的页面部件需要放在_includes文件夹中。

注意:不管文件的扩展名是md、html还是xml、txt,只要文件的头部包含变量声明,Jekyll的模板引擎就会对其进行处理。 其中md和html文件都会处理为html,其他类型会保持扩展名。

另外,liquid语法的引入,使得页面规则产生很大的变化,不能再简单的以markdown来写了。尤其是程序中带有大括号的。

写文章页面的定制

markdown文章可进一步定制:

---
layout: default
title: "这是标题"
date: 2014-04-23 09:45:26
description: "这是摘要"
categories: 这是存放的目录
tags: [话题1, 话题2]
lastmod: 2014-04-24
---

<h2>{{ page.title }}</h2>

<p>我的第一篇文章天地玄黄</p>

<p>{{ page.date | date: '%Y-%m-%d' }}</p>

说明:

定制导航

我是直接把 _layout/default.html 中的头部部分移到了新建文件 _include/header.html 中。

下面是 心内求法 同学的的设置,更加动态: 在 _config.yml 中定制

menuitems:
    - name:         首页
      url:          /index.html
    - name:         分类
      url:          /categories.html
    - name:         话题
      url:          /tags.html
    - name:         归档
      url:           /archive.html
    - name:         读书
      url:           /reading.html
    - name:         工作
      url:           /working.html
    - name:         我是谁
      url:           /about.html

然后在模板的导航部分添加:

<ul class="nav">
      {/% for item in site.menuitems %/}
        {/% if item.url == page.url %/}
        <li class="active">
        {/% else %/}
        <li>
        {/% endif %/}
        <a href=""></a>
        </li>
      {/% endfor %/}
    </ul>

注意:如果不是加入模板生成代码的话,可以直接用markdown来写,比如友情链接部分,用markdown来写明显比直接用html写来的高效。

定制首页

修改 index.html 文件,填入以下内容:

分类、话题(标签)、归档和RSS

文章摘要

如果有设定摘要的话,可以

{% if post.description %}<span>{{ post.description }}</span>{% endif %}

文章首段预览

如果需要文章首段预览的话,可加入:

<span>{{ post.excerpt }}</span>

话题(标签云)

js实现:

<div class="tag-cloud">
    {% for tag in site.tags %}
    <a href="/category/tags.html#{{ tag[0] }}-ref" id="{{ forloop.index }}" class="__tag" style="margin: 5px">{{ tag[0] }}</a>
    {% endfor %}
  </div>
  <script type="text/javascript">
   $(function() {
     var minFont = 12.0,
     maxFont = 36.0,
     diffFont = maxFont - minFont,
     size = 0;
     
     {% assign max = 1.0 %}
     {% for tag in site.tags %}
     {% if tag[1].size > max %}
     {% assign max = tag[1].size %}
     {% endif %}
     {% endfor %}
     
     {% for tag in site.tags %}
     size = (Math.log({{ tag[1].size }}) / Math.log({{ max }})) * diffFont + minFont;
     $("#{{ forloop.index }}").css("font-size", size + "px");
     {% endfor %}
   });
  </script>

分页

TODO: ajax分页 TODO: 浮动标题 on paginator

语法高亮

如下:其中,ruby是指定所用的代码名,linenos是显示行号

{% highlight ruby linenos %}
def foo
  puts 'foo'
end
{% endhighlight %}

效果如下:

def foo
    puts '长长长……长长长代码……长长长长代码……'
    puts '长长长……长长长代码……长长长长代码……'
    puts '长长长……长长长代码……长长长长代码……长长长……长长长代码……长长长长代码……'
end

更改样式,修改 css 文件夹下的 syntax.css

各种格式看看: ~~双波浪线删除线~~ 单下划线下划线 单星斜体 双下划线加粗 双星加粗

页内跳转

回到头部:

文档目录

如果写比较长的文章,提供一个类似于文档大纲,进行导航可以方便阅读。

两种方法:

另外,为了兼容性,比如有的手机框架关闭了浏览器本身的跳转功能,因此,用双向连接的方式可以获得最大的兼容性。

使用公式

渲染引擎支持公式否?是否需要系统装有 latex?

js渲染latex公式: Mathjax ,缺点是动态加载,速度慢。

优点:支持公式编号,这样方便引用

参考

试试 代码

<script type="text/javascript"
       src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
    </script>

处理图片

设置一个 IMAGE_ROOT 变量,可以在post中设置,也可以在post的模板中通过指定的规则capture(或者assign)。

则引可以使用/xxx.png的形式插入图片,便于以后的调整和管理。

处理表格

注:jekyll2之后,默认使用kramdown,可以自动处理表格。

注:如果是jekyll1,使用 redcarpet引擎,需要在 _config.yml 中,添加下面两行:

redcarpet:
    extensions: [tables]

参考并致谢:

使用github pages不支持的插件

问题:换用pandoc来渲染?

由于markdown+liquid会产生种种问题,因此,换用一种比较完美的转码方案。 不知道pandoc对自身语法的支持情况如何?

由于 Github Pages 并不支持 Pandoc,所以就需要在本地将站点完全生成好后再将它送到github上的gh-pages仓库里。

为何需要本地生成好网站?

虽然麻烦,但也带来几个优点:

  1. 本地生成,可以随心所欲地使用各种插件,或者换用别的静态站点生成器……
  2. 这样提交的是已经生成的成品,不用调用Github Pages生成,节省地球资源,也可以提高更新速度,不会出现今晚提交,明早才被更新好的情况。
  3. 麻烦的话,可以把操作过程封装为一条命令搞定,也就不麻烦了。

实现过程

  1. 安装pandoc
  2. 安装定制过的jekyll 定制的jekyll内容:修改 lib/jekyll/converters/markdown.rb 文件,在 setupconvert 中按照其它渲染器的格式增加一个 pandoc 判断即可。
  3. 安装pandoc的ruby接口:pandoc-ruby

  4. 修改 Jekyll 配置文件 _config.yml 如下:

     markdown: pandoc
     pandoc:
         extensions: [mathjax, standalone]
    

上面的 extensions 并不唯一,可以将任何 Pandoc 支持的选项加入其中。