Jekyll是一款在<staticgen.com>排名靠前的静态网站生成器。

安装和配置

根据Jekyll on Ubuntu,安装Ruby

sudo apt-get install ruby-full build-essential zlib1g-dev

Jekyll需要编译原生扩展,需要安装gcc, g++, make等。

根据RubyGems China,将Gems源改成国内的

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
gem sources -l
# 此处列出https://gems.ruby-china.com/ 

也可以手动修改.gemrc

安装jekyll和bundler:

gem install --user-install jekyll bundler

参考I installed gems with –user-install and their commands are not available。 然后因为用的是zsh和zim,所以需要在.zshenv中添加:

if which ruby >/dev/null && which gem >/dev/null; then
        export PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin:$PATH";
        export GEM_HOME="$(ruby -r rubygems -e 'puts Gem.user_dir')"
fi

如果时bash,则可以在.profile添加

设置Bundle,用ruby-china作为镜像(这样你不用改你的 Gemfile 的 source):

bundle config mirror.https://rubygems.org https://gems.ruby-china.com

jekyll最新的版本是4.2.1,但是Githu Pages使用的是3.9.0.

使用

创建一个新的site(设其名字为static-site):

jekyll new static-site
cd static-site

然后启动之:

bundle exec jekyll serve

bundle exec jekyll serve --livereload可以自动响应源代码变更重新加载网站

可以在http://127.0.0.1:4000/访问static-site的站点服务。

故障排除

开启下面的配置之后

kramdown:
    math_engine: katex

bundle exec jekyll serve遇到错误

  Conversion error: Jekyll::Converters::Markdown encountered an error while converting '_posts/2021-11-25-welcome-to-jekyll.markdown':
                    kramdown-math-katex

执行bundle add kramdown-math-katex

bundle exec jekyll serve的错误变成如下

Conversion error: Jekyll::Converters::Markdown encountered an error while converting '_posts/2021-11-25-welcome-to-jekyll.markdown':
                    Could not find a JavaScript runtime. See https://github.com/rails/execjs for a list of available runtimes.

根据Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)说是安装nodejs解决。

安装therubyracer不顶用。

Ruby在Windows下还是不能随便碰,在WSL中使用竟然把Windows搞得黑屏了一次,切记切记。

安装插件

bundle add --group jekyll_plugins  jekyll-coffeescript

配置主题

https://jekyllrb.com/docs/themes/讲怎么配置主题。如果要用到Github上,必须使用基于Gem的主题。受支持的主题罗列于此https://pages.github.com/themes/。默认的主题minima代码仓库在此https://github.com/jekyll/minima

bundle info --path minima可以查看主题安装文件

minima的最新版是2.5.1,已经是2019年发布了的,其_includes/head.html不支持:

{%- include custom-head.html -%}

于是想改用https://github.com/pages-themes/minimal,但是竟然没有用起来,

Github主页要求的是:

remote_theme: pages-themes/minimal@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

但是本地似乎无法预览主题应用的效果。而预览所需的gem "github-pages", group: :jekyll_plugins版本又太老了。

在安装主题minimal的时候遇到了问题,看来只有Github Pages上的版本是稳定的。

于是灵机一动,将remote_theme设为jekyll/minima,这样就使用到了最新的jekyll/minima,然后可以创建一个自定义的_includes\custom-head.html,加入Katex代码用以支持公式。

发布到Netlify

前面的步骤应该已经生成Gemfile.lock了,所以A Step-by-Step Guide: Jekyll 4.0 on Netlify中的开头的一些步骤可以省略。

然后就是在把static-site加入Git版本管理,推到Github上。

接着在https://app.netlify.com/里面,点击New site from Git,跟着流程走,Netlify就会在Github账户里面安装一个Netlify App。接着选择需要static-site所在那个仓库即可。

然后需要在编译环境中加入nodejs,根据https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-environment,只须在根目录加一个.node-version文件,里面填上数字16,即可自动使用nodejs第16版本的最新子版本。

最后就是域名以及https的一些配置吧。

其他

在Windows上安装ruby

ruby本身偏linux/unix环境,在windows下适配得不太好,不过还是可以试试https://rubyinstaller.org/的,这个installer是基于MSYS的。

scoop install ruby
scoop install msys2

把toolchain装上:ridk install,参考The ridk command

参考https://jekyllrb.com/docs/installation/windows/安装jekyll和bundler:gem install jekyll bundler,可以不用指定--user-install

执行bundle exec jekyll serve竟然出现下面的错误

 `require': cannot load such file -- webrick (LoadError)

解决方案是bundle add webrick,参考Load error: cannot load such file – webrick

然后jekyll的--livereload选项也不能用,需要参考Unable to load the EventMachine C extension; To use the pure-ruby reactor,通过gem uninstall eventmachine把eventmachine-1.2.7-x64-mingw32卸载,然后安装这个gem:gem 'eventmachine', '1.2.7', git: 'https://github.com/eventmachine/eventmachine.git', tag: 'v1.2.7'

上面的几点反映到Gemfile里面就是:

platforms :mingw, :x64_mingw, :mswin do
  gem "webrick", "~> 1.7"
  gem 'eventmachine', '1.2.7', git: 'https://github.com/eventmachine/eventmachine.git', tag: 'v1.2.7'
end

使用命令创建发帖

参考CREATE JEKYLL POSTS FROM THE COMMAND LINE

安装gem:

gem 'thor'
gem 'stringex'

然后在工程顶层目录创建jekyll.thor,内容如下:

require "stringex"
class Jekyll < Thor
  desc "new", "create a new post"
  method_option :editor, :default => "subl"
  def new(*title)
    title = title.join(" ")
    date = Time.now.strftime('%Y-%m-%d')
    filename = "_posts/#{date}-#{title.to_url}.markdown"

    if File.exist?(filename)
      abort("#{filename} already exists!")
    end

    puts "Creating new post: #{filename}"
    open(filename, 'w') do |post|
      post.puts "---"
      post.puts "layout: post"
      post.puts "title: \"#{title.gsub(/&/,'&amp;')}\""
      post.puts "tags:"
      post.puts " -"
      post.puts "---"
    end

    system(options[:editor], filename)
  end
end

创建发帖的命令是:

thor jekyll:new The title of the new post

其他参考链接

(本篇完)