Jekyll安装与部署

Published: by Creative Commons Licence (Last updated: )

Jekyll部署学习路线：

  • 先在本地安装并运行 jekyll，了解相关概念和命令
  • 再选择一个主题练手；此时应该会遇到相关插件未安装的问题
  • 详细介绍相关术语和命令
  • 了解相关配置 – 主要是 _config.yml文件的配置
  • 部署到GitLab Pages

Jekyll简介

中文网站 Jekyll • 简单静态博客网站生成器

Jekyll本地安装

可参考： Jekyll搭建个人博客
安装 - Jekyll • 简单静态博客网站生成器
搭建一个免费的，无限流量的Blog—-github Pages和Jekyll入门 - 阮一峰的网络日志
github上利用jekyll搭建自己的blog的操作顺序？ - 知乎
安装 - Jekyll • 简单静态博客网站生成器

操作系统不同，安装方法也会有所差异；这里是在xubuntu 16.04系统上进行安装

先安装Ruby环境

  • Ruby
  • RubyGems（对应的命令为gem）

ubuntu 16.04中可简单的通过 sudo apt install ruby来安装ruby和 ruby2.3，这会同时安装gem命令。

再安装jekyll

# 安装 bundler，用于Gemfile
$ gem install bundler 
# 安装jekyll
$ gem install jekyll

可能出现的错误：

错误1：

ERROR:  Error installing jekyll:
	ERROR: Failed to build gem native extension.

   current directory: /var/lib/gems/2.3.0/gems/ffi-1.9.18/ext/ffi_c
/usr/bin/ruby2.3 -r ./siteconf20170722-14451-ow9wuw.rb extconf.rb
mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

extconf failed, exit code 1

则缺少对应版本的ruby-dev，可通过如下命令安装：

sudo apt-get install ruby-dev

运行上述命令，在xubuntu 16.04中自动会下载对应版本的ruby-dev，比如我的ruby2.3

下列【新】软件包将被安装：
 libgmp-dev libgmpxx4ldbl ruby-dev ruby2.3-dev

错误2：对于该错误建议查看下面的所说的演示录像

运行命令：gem install bundler提示，没有写入权限

$ gem install bundler
Fetching: bundler-1.15.3.gem (100%)
ERROR:  While executing gem ... (Gem::FilePermissionError)
   You don't have write permissions for the /var/lib/gems/2.3.0 directory.

可以在命令前添加sudo解决问题，sudo gem install bundler，但是使得后面的多个命令都需要使用sudo(根据命令提示就可判断哪些需要添加sudo)；虽然这不是推荐的做法，但是它简单的就能解决问题。

其它解决办法可参考：
rubygems - You don't have write permissions for the /var/lib/gems/2.3.0 directory - Stack Overflow 还是不要执行卸载现有ruby版本的语句，它同时把多个软件卸载了。
"gem install bundler" issue on Ubuntu 16.04 - Stack Problems

或见此处的演示录像：install rbenv to opt - asciinema，录像大部分的时间浪费在下载和安装ruby的中间环节的上，播放时可跳过此段。

在本地创建并访问博客

# 创建博客
$ jekyll new myBlog
# 进入博客目录
$ cd myBlog
# 启动本地服务
$ jekyll serve
# 访问博客，在浏览器中输入启动服务成功后给出的地址
# 比如在浏览器中输入 http://127.0.0.1:4000

如果需要将网站托管到GitHub Pages或GitLab Pages则还需要你会用git。

Jekyll主题选择与安装

下载并重用他人制作的主题。

选择主题

Google上搜索jekyll主题：
Jekyll Themes
Dr. Jekyll's Themes - 211 free open source static website jekyll themes
Jekyll Themes：这里由几个好主题

找到的几个主题：

相对复杂的主题：

注意：有的主题是用来作为 project pages，并不适合用来写博客。

安装主题

以Kiko Plus主题：

具体步骤参考该主题在GitHub上的说明：Kiko-plus: Simple theme for jekyll blog

如遇到问题，可看下文，比如"jekyll插件"部分。

这里我遇到的一个问题是：部署后博客的tags标签页下没有任何东西。

问题原因：在全局.gitignore 文件中，忽略了 tags 目录。
解决办法：在本Project的.gitignore中添加!tags，来跟踪tags文件。

jekyll-theme-simple-texture 主题

作者主页：http://yizeng.me/ ；作者主页源码https://github.com/yizeng/yizeng.me 可查看其配置。

Ruby相关概念

Jekyll 是基于 Ruby 开发的，所以会用到Ruby的相关命令。

理解几个名词：

RubyGems： 是 Ruby 的一个包管理器，它提供一个分发 Ruby 程序和库的标准格式，还提供一个管理程序包安装的工具。这类似于 Ubuntu 下的apt-get, Centos 的 yum，Python 的 pip。它对应的命令为 gem。

gem命令：用于构建、上传、下载以及安装Gem包。

Gem： 是 Ruby 模块 (叫做 Gems) 的包管理器。其包含包信息，以及用于安装的文件。A Gem is a bundle of code，Jekyll就是一个Gem，还有大多数的Jekyll插件都是Gem。

RubyGems.org 站点是代码库的主要集散地，它提供 Gem 形式的代码库。你可以直接访问其网站或者使用 gem 命令。（ Gem 会被发布到 RubyGems.org）。

国内源：
由于国内网络原因，导致 rubygems.org 存放在 Amazon S3 上面的资源文件间歇性连接失败。我们可以将它修改为淘宝下载源: http://ruby.taobao.org/ ,另还有 https://gems.ruby-china.org/

首先，查看当前源：gem sources -l（这里有个坑，如果列出的url地址的末尾是/那么替换时一定也要包含该/）

移除原有源，添加淘宝源（需确保只要一个源）：

gem sources --remove https://rubygems.org/
gem sources -a https://ruby.taobao.org/
gem sources -l

如果使用Gemfile和Bundle，可以使用如下源代码镜像命令：

bundle config mirror.https://rubygems.org https://ruby.taobao.org

这样你不用改你的 Gemfile 中的 source。

参考 Ruby RubyGems 菜鸟教程 、代码库。

gemfile：包含当前Ruby项目需要运行的Gems列表。

当我们需要为Jekyll项目添加插件时，我们可以使用Gemfiles来指定。

需要在Gemfiles文件的开头，至少指定一个gem source(指向RubyGems server的url)；

可以通过执行命令bundle init来创建一个gemfile，其默认source为https://rubygems.org

详见 What is a Gemfile。

Bundler：一个用于管理应用依赖关系的通用工具，它可以跟 RubyGems 搭配使用。通过Bundler程序读取Gemfile然后下载文件中需要的Gems。

当我们更改了Gemfile文件后，需要运行bundle install命令，该命令生成Gemfile.lock文件，并下载该文件中的gems。

bundle install --path vendor/bundle

一般我们在初次运行 bundle install时会使用--path选项，该选项用于指定该项目中使用到的 Gems 的下载安装路径；之后使用bundle install时就无需指定--path。

不要使用root权限安装bundler，不然之后的大多数命令都需要使用root权限.

Bundler能为我们选择正确的gem版本：当我们运行jekyll serve时，如果我们有一个插件jekyll-feed，并且该插件在我们的电脑上有多个版本，此时jekyll serve就可能选择了错误的版本；我们可以使用bundle exec来解决这个问题，它只会使用Gemfile中该gem需要的版本，示例：使用bundle exec jekyll serve代替jekyll serve。

执行bundle exec jekyll serve或jekyll serve后便会生成一个_site目录，这就是生成的网站。使用版本控制时建议排除_site目录。Before building the site, it actually doesn't exist and is just a bunch of template files。

jekyll serve命令的几个作用：

  1. 构建您的站点（使用build命令）；
  2. 启动开发服务器，并在默认情况下监测文件变化并进行实时构建。任何时候发生变化，它将自动构建您的网站。

jekyll build命令：该命令用于创建静态站点(生成_site目录)。

jekyll new命令：该命令会使用默认的主题，创建一个新的jekyll网站框架(项目).

以下几篇文章都讲解了 Gem、GemFile、Bundler。
Gems, Gemfiles and the Bundler - CloudCannon Academy
Getting Started with Jekyll (plus a Free Bootstrap 3 Starter Theme) ― Scotch
Quick-start guide - Jekyll • Simple, blog-aware, static sites
Bundler: Developing a RubyGem using Bundler
How to create a blog with Jekyll (like this one) · Matt's Blog

Bundler用于在Ruby库中管理Rubygems依赖项。

在Gemfile中的gem "jekyll-seo-tag"相当于单独执行命令gem install 'jekyll-seo-tag'；但前者只应用与当前项目，后者则属于全局安装与某个项目无关。

Jekyll插件

当下载使用他人的主题时，运行 jekyll serve或jekyll s或jekyll build命令后，可能出现的错误。

插件相关的错误：

第一个错误：某些主题在_config.yml配置文件中使用 gems而非plugins。

The 'gems' configuration option has been renamed to 'plugins'. Please update your config file accordingly.
只需将： gems 改为 plugins 即可

之后的错误，大多数是提示相关插件没有安装，无法找到。没找到就安装该插件。

具体步骤：

  • 查看该主题_config.yml文件中指定了哪些插件
  • 新建Gemfile文件，并在该文件中添加这些插件
  • 运行 bundler install安装这些插件；或使用bundle install --path vendor/bundle 此时推荐将vendor目录添加到 .gitignore 文件中
  • 再次运行 jekyll serve

插件的安装方法：

一般方法，先在Gemfile中添加，然后再在_config.yml文件的plugins下添加。

Gemfile文件内容：

# frozen_string_literal: true
source "https://rubygems.org"

# Kiko Plus 主题所需插件，下面的内容需要根据实际情况进行配置，不能重用
# 并且需要在_config.yml文件的plugins下进行添加
gem 'jekyll-seo-tag'
gem 'jekyll-paginate'
gem 'jekyll-admin'

对应的 _config.yml文件中的相应内容：

plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jemoji

几个插件介绍：

_config.yml配置文件

1、URL的配置

如果需要部署到GitHub pages，URL一定要配置好。

# URL
url:                "https://fandean.github.io" # the base hostname 主机名 & 协议 protocol for your site 
# url:                "http://localhost:4000" # use this url when you develop
baseurl:            "\blog" # the subpath of your site（网站的子路径,可以为空）, e.g. /blog 
# 访问你该网站首页的路径为： url + baseurl = https://fandean.github.io/blog

2、Permalinks固定链接

引用变量的方法:变量，那么没有:前缀的就是固定字符。

在配置文件_config.yml中有：

permalink:          /:year-:month-:day/:title/

以上固定链接表示： 文章生成的html保存在类似_site/2017-01-19/style-test-ko/index.html路径中。 其中_site根目录 = url + baseurl，title目录为 style-stest-ko，它是这篇文章的标题，最终的文章内容将保存在index.html文件中。

Jekyll预定义了几个固定链接的格式：比如 date表示/:categories/:year/:month/:day/:title.html ；我们可以简单的使用permalink:date来指定。其中categories表示分类，应该需要事先在markdown中指定。

在您的帖子，页面或集合的Front Matter中的permalink会覆盖任何全局设置，例如：

---
title: My page title
permalink: /mypageurl/
---

该Front Matter中的permalink表示该文章会保存在网站的/mypageurl/目录下，这里没有:前缀所以是固定字符。

参考：Permalinks - Jekyll • Simple, blog-aware, static sites

配置文件错误：Page build failed: Config file error - User Documentation

更多错误： Troubleshooting GitHub Pages builds - User Documentation

有些有 timezone时区设置：示例 上海：Asia/shanghai 香港：Asia/Hong_Kong

GitLab Pages部署jekyll

GitHub Pages 的背后就运行着 Jekyll

由于GitHub Pages在国内访问不畅，所以选择了GitLab Pages。

  1. 先在本地配置好jekyll，运行测试。比如下载相关主题，并按该主题的相关指导进行部署。
  2. 将jekyll push到gitlab进行托管，远程仓库名称为username.gitlab.io，根据gitlab给出的命令提示，执行相关命令。（建议先配置好.gitignore文件）
  3. 添加.gitlab-ci.yml文件:
    在GitLab网站，进入该Project，选择Project标签页，点击"Set up CI"，在出现的界面中点击"Apply a GitLab CI Yaml template"下拉列表，并选择Jekyll，直接使用给出的模板即可；然后提交更改。
  4. 如果之前没有添加Gemfile，则添加该文件，在Gemfile文件中添加该工程需要的插件。Gemfile的说明见前文，示例见下面的引用。
  5. 构建该Project：GitLab可能会为你自动构建；你也可通过Pipelines标签页进行查看，或手动运行。构建通过会显示有passed字样。
  6. 通过setting标签页 --> Pages 查看访问该pages的url。点击该url即可进入页面。

这里讲解了怎样在GitLab中为GitLab Pages创建和调整.gitlab-ci.ymlGitLab Pages from A to Z: Part 4 - GitLab Documentation ，详细讲解了该文件的配置。.gitlab-ci.yml文件内容：


image: ruby:2.3  # Use Ruby Docker image

cache:  # Add Bundler cache to 'vendor' directory
  paths:
    - vendor/

before_script:  # Install Gems to 'vendor' directory  要执行的命令
  - bundle install --path vendor

test:
  stage: test
  script:  # Generate test site(s) into 'test' directory 
  - bundle exec jekyll build -d test
      artifacts:  # Save a zipped version for download
    paths:
    - test
  except:  # Execute for all branches except master
  - master

pages:      # pages  job，它告诉Runner您希望该任务使用GitLab页面部署您的网站
  stage: deploy
  script:  # Generate public site and deploy。 需要执行的命令；命令 --> script
  - bundle exec jekyll build -d public
      artifacts:  # Save a zipped version for download
    paths:
    - public
  only:  # Only deploy the master branch
  - master

根据上面的配置文件，在部署网站时会执行两条命令：

bundle install --path vendor 和

bundle exec jekyll build -d public

一个Gemfile文件示例：

# frozen_string_literal: true
source "https://rubygems.org"

# Kiko Plus 主题所需插件，下面的内容需要根据实际情况进行配置，不能重用
# 并且需要在_config.yml文件的plugins下进行添加
gem 'jekyll-seo-tag'
gem 'jekyll-paginate'
gem 'jekyll-admin'

更多示例: README.md · master · Jekyll Themes / Build Jekyll with Bundler · GitLab

相关视频：How to Publish a Website with GitLab Pages - YouTube

README.md · master · Jekyll Themes / Build Jekyll with Bundler · GitLab