Jekyll站点生成器本地环境搭建

背景

许多开源软件的文档和站点生成器都采用Jekyll作为首选，比如Apache基金会下的Hive、Spark、Calcite等开源项目都采用Jekyll构建官方站点。看源码的时候如果遇到一些问题而此时没有网络的情况下阅读源码中携带的markdown文件多少有点不舒服，如果本地能发布一套那么再阅读起来就毫无不适感了。电脑为MacOS Big Sur版本号11.6，发布过程中出现的几个问题记录一下方便后续换电脑后可以快速完成环境配置。

Jekyll介绍

Jekyll是一个静态站点生成器，用户可以根据自身的偏好选择标记语言编写文本，Jekyll将结合主题的样式及布局创建一个静态网站。用户可以调整网站的外观、URL以及页面上显示的数据等等。通常用于生成个人项目或组织的静态站点。 Jekyll由GitHub联合创始人汤姆·普雷斯顿·沃纳采用Ruby编写，并基于MIT许可证发布。

Jekyll历史

Jekyll由Tom Preston-Werner于2008年首次发布，后来被帕克·摩尔（Parker Moore）接管并由他领导发布Jekyll 1的工作，此后该开源项目的维护一直由他主导。GitHub Pages则是GitHub于2008年推出的一个网页寄存服务，可以用于存放静态网页包括博客、项目文档甚至整本书。在GitHub Pages的加持下，截至2017年Jekyll一跃成为了最受欢迎的静态站点生成器。

Jekyll特点

Jekyll非常灵活，可以与Bootstrap、Semantic UI等前端框架结合使用；
Jekyll静态站点可以连接到基于云的CMS软件，例如CloudCannon，Forestry， Netlify或Siteleaf，使编辑者无需具备编程知识即可修改网站内容；
Jekyll不使用数据库，用户通过编写Markdown、Textile或Liquid文件即可生成一个完整的静态站点，可以通过Apache HTTP Server，Nginx或其他Web服务器提供服务；

Jekyll的核心是一个文本转换引擎。它的方便之处在于支持多种文本标记语言：Markdown，Textile，HTML，用户编写完成后Jekyll 会帮用户将内容加入所选择主题的样式布局中，最终生成一个静态博客或者站点。 Jekyll站点目录结构如下：

.
├── _config.yml
├── _data
│   └── members.yml
├── _drafts
│   ├── begin-with-the-crazy-ideas.md
│   └── on-simplicity-in-technology.md
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│   ├── _base.scss
│   └── _layout.scss
├── _site
├── .jekyll-cache
│   └── Jekyll
│       └── Cache
│           └── [...]
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter

├── _config.yml

├── _data

│ └── members.yml

├── _drafts

│ ├── begin-with-the-crazy-ideas.md

│ └── on-simplicity-in-technology.md

├── _includes

│ ├── footer.html

│ └── header.html

├── _layouts

│ ├── default.html

│ └── post.html

├── _posts

│ ├── 2007-10-29-why-every-programmer-should-play-nethack.md

│ └── 2009-04-26-barcamp-boston-4-roundup.md

├── _sass

│ ├── _base.scss

│ └── _layout.scss

├── _site

├── .jekyll-cache

│ └── Jekyll

│ └── Cache

│ └── [...]

├── .jekyll-metadata

└── index.html # can also be an 'index.md' with valid front matter

Jekyll安装异常记录

Jekyll基于Ruby，因此安装之前先熟悉Ruby相关的几个概念：

Ruby是一种面向对象、指令式、函数式、动态的通用编程语言；
gem是一组Ruby程序（叫做 Gems）的包管理器，其包含包信息以及用于安装的文件，类似于“包”的概念；
RubyGems是Ruby的一个包管理器，它提供一个分发Ruby程序和库的标准格式，还提供一个管理程序包安装的工具，似于Ubuntu下的apt-get，Centos的yum以及Python的pip；
bundler管理Ruby项目中所需要的Gem包，能够跟踪并安装所需的特定版本的gem；

warning: Insecure world writable dir

根据官网安装操作指南执行安装命令，提示目录没有写入权限：

[w3sun@w3sundeMacBook-Pro ~] gem install jekyll bundler
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/universal-darwin20/rbconfig.rb:229: warning: Insecure world writable dir /opt/bigdata in PATH, mode 040777
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

[w3sun@w3sundeMacBook-Pro ~] gem install jekyll bundler

/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/universal-darwin20/rbconfig.rb:229: warning: Insecure world writable dir /opt/bigdata in PATH, mode 040777

ERROR: While executing gem ... (Gem::FilePermissionError)

You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

因为操作系统时MacOS，对目录添加写权限时执行如下命令即可：

[w3sun@w3sundeMacBook-Pro ~] sudo chmod go-w /opt/bigdata

1	[w3sun@w3sundeMacBook-Pro ~] sudo chmod go-w /opt/bigdata

error: /Library/Ruby/Gems/2.6.0无写入权限

安装时提供sudo权限即可顺利安装：

[w3sun@w3sundeMacBook-Pro ~] sudo gem install jekyll bundler
Successfully installed jekyll-4.2.2
Parsing documentation for jekyll-4.2.2
Done installing documentation for jekyll after 0 seconds
Successfully installed bundler-2.3.12
Parsing documentation for bundler-2.3.12
Done installing documentation for bundler after 0 seconds
2 gems installed

[w3sun@w3sundeMacBook-Pro ~] sudo gem install jekyll bundler

Successfully installed jekyll-4.2.2

Parsing documentation for jekyll-4.2.2

Done installing documentation for jekyll after 0 seconds

Successfully installed bundler-2.3.12

Parsing documentation for bundler-2.3.12

Done installing documentation for bundler after 0 seconds

2 gems installed

基础环境安装完成后可以通过创建一个博客站点进行环境验证：

[w3sun@w3sundeMacBook-Pro ~] jekyll new myblog
Running bundle install in /Users/w3sun/github/myblog...
  Bundler: Fetching gem metadata from https://rubygems.org/..........
  Bundler: Resolving dependencies...
  Bundler: Using bundler 2.3.12
  Bundler: Using colorator 1.1.0
  Bundler: Using concurrent-ruby 1.1.10
  Bundler: Using eventmachine 1.2.7
  Bundler: Using http_parser.rb 0.8.0
  Bundler: Using ffi 1.15.5
  Bundler: Using public_suffix 4.0.7
  Bundler: Using forwardable-extended 2.6.0
  Bundler: Using rb-fsevent 0.11.1
  Bundler: Fetching rexml 3.2.5
  Bundler: Using liquid 4.0.3
  Bundler: Using mercenary 0.4.0
  Bundler: Using safe_yaml 1.0.5
  Bundler: Using rouge 3.28.0
  Bundler: Using i18n 1.10.0
  Bundler: Using unicode-display_width 1.8.0
  Bundler: Using sassc 2.4.0
  Bundler: Using rb-inotify 0.10.1
  Bundler: Using pathutil 0.16.2
  Bundler: Using em-websocket 0.5.3
  Bundler: Using jekyll-sass-converter 2.2.0
  Bundler: Using addressable 2.8.0
  Bundler: Using terminal-table 2.0.0
  Bundler: Using listen 3.7.1
  Bundler: Using jekyll-watch 2.2.1
  Bundler: Installing rexml 3.2.5
  Bundler: Using kramdown 2.3.2
  Bundler: Using kramdown-parser-gfm 1.1.0
  Bundler: Using jekyll 4.2.2
  Bundler: Fetching jekyll-seo-tag 2.8.0
  Bundler: Fetching jekyll-feed 0.16.0
  Bundler: Installing jekyll-seo-tag 2.8.0
  Bundler: Installing jekyll-feed 0.16.0
  Bundler: Fetching minima 2.5.1
  Bundler: Installing minima 2.5.1
  Bundler: Bundle complete! 7 Gemfile dependencies, 31 gems now installed.
  Bundler: Use `bundle info [gemname]` to see where a bundled gem is installed.
New jekyll site installed in /Users/w3sun/github/myblog.

[w3sun@w3sundeMacBook-Pro ~] jekyll new myblog

Running bundle install in /Users/w3sun/github/myblog...

Bundler: Fetching gem metadata from https://rubygems.org/..........

Bundler: Resolving dependencies...

Bundler: Using bundler 2.3.12

Bundler: Using colorator 1.1.0

Bundler: Using concurrent-ruby 1.1.10

Bundler: Using eventmachine 1.2.7

Bundler: Using http_parser.rb 0.8.0

Bundler: Using ffi 1.15.5

Bundler: Using public_suffix 4.0.7

Bundler: Using forwardable-extended 2.6.0

Bundler: Using rb-fsevent 0.11.1

Bundler: Fetching rexml 3.2.5

Bundler: Using liquid 4.0.3

Bundler: Using mercenary 0.4.0

Bundler: Using safe_yaml 1.0.5

Bundler: Using rouge 3.28.0

Bundler: Using i18n 1.10.0

Bundler: Using unicode-display_width 1.8.0

Bundler: Using sassc 2.4.0

Bundler: Using rb-inotify 0.10.1

Bundler: Using pathutil 0.16.2

Bundler: Using em-websocket 0.5.3

Bundler: Using jekyll-sass-converter 2.2.0

Bundler: Using addressable 2.8.0

Bundler: Using terminal-table 2.0.0

Bundler: Using listen 3.7.1

Bundler: Using jekyll-watch 2.2.1

Bundler: Installing rexml 3.2.5

Bundler: Using kramdown 2.3.2

Bundler: Using kramdown-parser-gfm 1.1.0

Bundler: Using jekyll 4.2.2

Bundler: Fetching jekyll-seo-tag 2.8.0

Bundler: Fetching jekyll-feed 0.16.0

Bundler: Installing jekyll-seo-tag 2.8.0

Bundler: Installing jekyll-feed 0.16.0

Bundler: Fetching minima 2.5.1

Bundler: Installing minima 2.5.1

Bundler: Bundle complete! 7 Gemfile dependencies, 31 gems now installed.

Bundler: Use `bundle info [gemname]` to see where a bundled gem is installed.

New jekyll site installed in /Users/w3sun/github/myblog.

以非超级用户身份运行 Jekyll（非sudo）

大多数Linux、macOS以及Windows的Ubuntu子系统都可以通过设置shell的配置文件实现非超级用户身份运行Jekyll的目的，否则每次运行都会出现如下提示：

本人用的是zsh所以编辑~/.zshrc，在其中新增变量GEM_HOME并加入PATH变量中即可：

export GEM_HOME=/Users/w3sun/gems
export PATH=.:$PATH:$GEM_HOME/bin

1 2	export GEM_HOME=/Users/w3sun/gems export PATH=.:$PATH:$GEM_HOME/bin

环境测试正常可以将Hive、Spark及Calcite等开源框架的本地文档进行本地发布，下一篇关于Jekyll的文章将介绍下如何结合Github Pages和域名设置发布公网可访问站点。