记录下Jekyll的本地化配置以及遇到的问题
安装Ruby
从官网下载 带Devkit的Ruby版本,我这里选用 Ruby+Devkit 2.6.6-1 (x64),然后一路next安装,Devkit 的勾选一定要勾上。
安装Jekyll
输入命令在线安装
gem install jekyll
配置Jekyll
TOC
Table of Contect
kramdown 默认支持 TOC 功能
在需要插入目录的地方加入如下内容
* toc
{:toc}
语法高亮
highlighter: rouge # Ruby语言使用rouge代码高亮引擎 #
markdown: kramdown
kramdown:
input: GFM
之后只需在添加代码的地方注明什么语言即可自动高亮显示。
公式渲染
对比Katex和MathJax,性能参考这个链接,在此选用MathJax,配置如下:
<script>
MathJax = {
tex: {
inlineMath: [['$', '$']]
},
};
</script>
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js">
</script>
启动本地Jekyll
bundle exec jekyll serve
遇到的错误
错误一
Liquid Exception: undefined method map' for false:FalseClass Did you mean? tap in /_layouts/about.html
jekyll 3.8.7 | Error: undefined methodmap' for false:FalseClass
解决办法
打开 C:\Ruby26-x64\lib\ruby\gems\2.6.0\gems\jekyll-3.8.7\lib\jekyll\filters.rb 文件,在305行
def sort_input(input, property, order)
if !input #################加入这三行
return #################加入这三行
end #################加入这三行
input.map { |item| [item_property(item, property), item] }
.sort! do |apple_info, orange_info|
apple_property = apple_info.first
orange_property = orange_info.first
if !apple_property.nil? && orange_property.nil?
- order
elsif apple_property.nil? && !orange_property.nil?
+ order
else
apple_property <=> orange_property
end
end
.map!(&:last)
end
错误二
文本啥的都是UTF-8编码,居然找不到文章。
解决办法
发现是http的服务器上的地址编码不一致导致,找到C:\Ruby26-x64\lib\ruby\2.6.0\webrick\httpservlet\filehandler.rb,在 286和334行都加上path.force_encoding(“UTF-8”):
def prevent_directory_traversal(req, res)
# Preventing directory traversal on Windows platforms;
# Backslashes (0x5c) in path_info are not interpreted as special
# character in URI notation. So the value of path_info should be
# normalize before accessing to the filesystem.
# dirty hack for filesystem encoding; in nature, File.expand_path
# should not be used for path normalization. [Bug #3345]
path = req.path_info.dup.force_encoding(Encoding.find("filesystem"))
path.force_encoding("UTF-8") #################强制使用UTF-8编码
if trailing_pathsep?(req.path_info)
# File.expand_path removes the trailing path separator.
# Adding a character is a workaround to save it.
# File.expand_path("/aaa/") #=> "/aaa"
# File.expand_path("/aaa/" + "x") #=> "/aaa/x"
expanded = File.expand_path(path + "x")
expanded.chop! # remove trailing "x"
else
expanded = File.expand_path(path)
end
expanded.force_encoding(req.path_info.encoding)
req.path_info = expanded
end
def set_filename(req, res)
res.filename = @root.dup
path_info = req.path_info.scan(%r|/[^/]*|)
path_info.unshift("") # dummy for checking @root dir
while base = path_info.first
break if base == "/"
base.force_encoding("UTF-8")#################强制使用UTF-8编码
break unless File.directory?(File.expand_path(res.filename + base))
shift_path_info(req, res, path_info)
call_callback(:DirectoryCallback, req, res)
end
if base = path_info.first
if base == "/"
if file = search_index_file(req, res)
shift_path_info(req, res, path_info, file)
call_callback(:FileCallback, req, res)
return true
end
shift_path_info(req, res, path_info)
elsif file = search_file(req, res, base)
shift_path_info(req, res, path_info, file)
call_callback(:FileCallback, req, res)
return true
else
raise HTTPStatus::NotFound, "`#{req.path}' not found."
end
end
return false
end
错误三
公式的渲染很慢,而且由于比较慢,导致部分公式渲染失败。
解决办法
参考公式效率对比,发现使用MathJax3速度很快,为了进一步速度优化,使用国内的CDN,这里推荐使用 Staticfile CDN 上的库。
将以下代码复制进网页头部分:
<script>
MathJax = {
tex: {
inlineMath: [['$', '$']],
displayMath: [['$$', '$$']],
processEnvironments: true,
processRefs: true
},
options: {
skipHtmlTags: ['noscript', 'style', 'textarea', 'pre', 'code'],
ignoreHtmlClass: 'tex2jax_ignore',
renderActions: {
find_script_mathtex: [10, function (doc) {
for (const node of document.querySelectorAll('script[type^="math/tex"]')) {
const display = !!node.type.match(/; *mode=display/);
const math = new doc.options.MathItem(node.textContent, doc.inputJax[0], display);
const text = document.createTextNode('');
node.parentNode.replaceChild(text, node);
math.start = { node: text, delim: '', n: 0 };
math.end = { node: text, delim: '', n: 0 };
doc.math.push(math);
}
}, '']
}
},
svg: {
fontCache: 'global'
}
};
</script>
<script id="MathJax-script" async src="https://cdn.staticfile.org/mathjax/3.0.1/es5/tex-svg.js"></script>
另外如有有其它配置需求,可以看看下面的官网配置解释
MathJax = {
tex: {
packages: ['base'], // extensions to use
inlineMath: [ // start/end delimiter pairs for in-line math
['\\(', '\\)']
],
displayMath: [ // start/end delimiter pairs for display math
['$$', '$$'],
['\\[', '\\]']
],
processEscapes: true, // use \$ to produce a literal dollar sign
processEnvironments: true, // process \begin{xxx}...\end{xxx} outside math mode
processRefs: true, // process \ref{...} outside of math mode
digits: /^(?:[0-9]+(?:\{,\}[0-9]{3})*(?:\.[0-9]*)?|\.[0-9]+)/,
// pattern for recognizing numbers
tags: 'none', // or 'ams' or 'all'
tagSide: 'right', // side for \tag macros
tagIndent: '0.8em', // amount to indent tags
useLabelIds: true, // use label name rather than tag for ids
multlineWidth: '85%', // width of multline environment
maxMacros: 1000, // maximum number of macro substitutions per expression
maxBuffer: 5 * 1024, // maximum size for the internal TeX string (5K)
baseURL: // URL for use with links to tags (when there is a <base> tag in effect)
(document.getElementsByTagName('base').length === 0) ?
'' : String(document.location).replace(/#.*$/, ''))
}
};