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

其他参考链接

（本篇完）

2023-01-26更新：部署Next.js到Netlify

Netlify Next.js相关的导览页面https://www.netlify.com/with/nextjs/

Netlify Next.js 相关的文档Next.js on Netlify。

关于Next.js的建构命令和输出目录，根据https://docs.netlify.com/integrations/frameworks/#next-js，分两种

  • 使用server-side rendering 以及Next.js runtime
    • 建构使用next build，输出目录.next
  • 使用static HTML export
    • 建构使用next build && next export，输出目录out

实际可以替换成npm run build等。

一些需要注意的问题：

（更新完）