0. 前言

今天写了一篇文章,发布的时候居然告诉我jekyll没有安装,估计是之前系统更新的问题,只能重新装一遍。结果问题还真不少,这里简单记录下。

1. 安装

1.1 安装rvm | 更新ruby

系统默认带的ruby版本是2.0.0,太老了,需要更新。

curl -sSL https://get.rvm.io | bash -s stable
rvm list known
rvm install ruby-2.4.0 --verbose
rvm use ruby-2.4.0 --default

1.2 更新gem源

删掉所有莫名其妙的源

gem sources -r ${source}

添加官方唯一的源

gem sources -a https://rubygems.org/

1.3 安装Jekyll

别问我为什么需要sudo,这货就是需要权限

sudo gem install jekyll --verbose

1.4 安装语法高亮

我使用的时候报了个错:

Dependency Error: Yikes! It looks like you don’t have pygments or one of its dependencies installed. In order to use Jekyll as currently configured, you’ll need to install this gem. The full error message from Ruby is: ‘cannot load such file – pygments’

安装pygments的时候报错:

sudo gem install pygments --verbose
# Password:
# HEAD https://api.rubygems.org/api/v1/dependencies
# 200 OK
# GET https://api.rubygems.org/api/v1/dependencies?gems=pygments
# 200 OK
# ERROR:  Could not find a valid gem 'pygments' (>= 0) in any repository
# GET https://api.rubygems.org/latest_specs.4.8.gz
# 200 OK
# ERROR:  Possible alternatives: pigments, rygments, pigment, rb-pygments, segments

结果找了半天,正确的gem名字应该是:pygments.rb

sudo gem install pygments.rb --verbose

UPDATE 2018-01-18

添加gist插件:jekyll-gist

gem install jekyll-gist
# ...
# Done installing documentation for multipart-post, faraday, sawyer, octokit, jekyll-gist after 2 seconds
# 5 gems installed

修改站点配置_config.yml

plugins:
  - jekyll-gist

UPDATE 2018-01-22

添加toc插件:jekyll-toc

gem install jekyll-toc
# ...
# Done installing documentation for mini_portile2, nokogiri, jekyll-toc after 9 seconds
# 3 gems installed 

修改站点配置_config.yml

plugins:
  - jekyll-toc

然后修改_layouts/post.html,把\{\{ content \}\}改成\{\{ content | toc \}\},就能在文章头部显示默认的toc了。

UPDATE 2018-02-07

停用toc插件:jekyll-toc。

这两天稍微研究了下Kramdown这个markdown渲染工具(现在博客使用的模板里默认就是这个),其实这个工具功能极其强大,里面默认集成了一堆常用的功能集合,只要开启就好了。

TOC

创建一个文件_includes/toc.html,内容:

\<h4>Table of Contents</h4>
\* this unordered seed list will be replaced by toc as unordered list
\{:toc}

注意删除转译符。

然后修改站点配置_config.yml

markdown: kramdown
kramdown:
  input: GFM # Enable GitHub Flavored Markdown (fenced code blocks)
  toc_levels: 1..6
  auto_ids: true

最后在需要TOC的文章中,在文章需要添加TOC的部位加上:

{\% include toc.html \%}

就OK了。注意删除转译符。

超链接

在正常的Markdown超链接后面加上{:target="_blank"},就能让超链接在新窗口打开。

标题ID

根据上面TOC部分的指引,就能够自动在所有的标题上添加ID(为了自动生成的TOC锚链接)。但因为链接的ID使用的是标题的文本内容,如果标题是中文之类的,在使用标题ID的时候会非常难。

Kramdown自带了标题ID生成功能:

# 1. 前言 {#ID1}

这样生成出来的标题就带了ID:<h1 id="ID1">1. 前言</h1>

然后在文章中使用

[跳转到ID1](#ID1)

这样的语法,就能快速跳转到锚链接点。

其他

其他一些好用的特性可以查看:kramdown和markdown较大的差异比较

EOF