installation

ubuntu 16.04

Install Ruby on Ubuntu (16.04), see Ruby gem

sudo gem install jekyll --verbose

macOS 10.13

macOS shiped with ruby and gem

$ ruby -v
ruby 2.2.6p396 (2016-11-15 revision 56800) [x86_64-darwin16]
$ gem -v
2.6.12

install jekyll and bundler

$ gem install jekyll bundler

Prepare project document dir

$ mkdir doc
$ cd doc
$ cat _config.yml
source: "/tmp/doc"
destination: "/tmp/site"
$ cat _layouts/default.html
<title>Jekyll</title>
<div><article class="post">

  <header class="post-header">
    <h1 class="post-title">JDK</h1>
  </header>

  <div class="post-content">
    <h2 id="install-jdk-on-macos">install jdk on macOS</h2>

<p><a href="https://stackoverflow.com/a/28635465">How to install Java 8 on Mac</a></p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>brew update
brew cask install java
</code></pre></div></div>

<h2 id="see-also">See also</h2>

<ul>
  <li><a href="/java.html">java</a></li>
  <li><a href="/homebrew.html">Homebrew</a></li>
</ul>

  </div>

</article>
</div>

create first document

$ cd doc
$ cat index.md
---
layout: page
title: index
---

- 1
- 2

Build document

$ cd doc
$ jekyll build

Result

$ cd /tmp/site
$ cat index.html
<title>index</title>
<div><ul>
  <li>1</li>
  <li>2</li>
</ul></div>

如果代码中有liquid语法

可以使用和将这一部分注释掉。

如果无法加载_plugins下的插件，先检查site.safe是否是disable

$ bundle exec jekyll serve --trace 
Configuration file: /home/chenyang/source/xxd3vin.github.io/_config.yml
            Source: /home/chenyang/source/xxd3vin.github.io
       Destination: /home/chenyang/source/xxd3vin.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
    Liquid Warning: Liquid syntax error (line 5): Unexpected character # in "{{#jiandanurl: tesejiaoyuzhanlanguan }}" in mediawiki.md
  Liquid Exception: Liquid syntax error (line 17): Unknown tag 'plantuml' in plantuml.md
/var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/block.rb:87:in `unknown_tag': Liquid syntax error (line 17): Unknown tag 'plantuml' (Liquid::SyntaxError)
	from /var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/block.rb:38:in `parse'
	from /var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/tag.rb:10:in `parse'
	from /var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/document.rb:5:in `parse'
	from /var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/template.rb:122:in `parse'
	from /var/lib/gems/2.1.0/gems/liquid-3.0.6/lib/liquid/template.rb:108:in `parse'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/liquid_renderer/file.rb:11:in `block in parse'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/liquid_renderer/file.rb:47:in `measure_time'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/liquid_renderer/file.rb:10:in `parse'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/renderer.rb:109:in `render_liquid'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/renderer.rb:62:in `run'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/site.rb:458:in `block in render_pages'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/site.rb:456:in `each'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/site.rb:456:in `render_pages'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/site.rb:191:in `render'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/site.rb:69:in `process'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/command.rb:26:in `process_site'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/commands/build.rb:63:in `build'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/commands/build.rb:34:in `process'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/lib/jekyll/commands/serve.rb:36:in `block (2 levels) in init_with_program'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `call'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `block in execute'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `each'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `execute'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary/program.rb:42:in `go'
	from /var/lib/gems/2.1.0/gems/mercenary-0.3.6/lib/mercenary.rb:19:in `program'
	from /var/lib/gems/2.1.0/gems/jekyll-3.2.1/exe/jekyll:13:in `<top (required)>'
	from /usr/local/bin/jekyll:23:in `load'
	from /usr/local/bin/jekyll:23:in `<main>'

也有可能是因为在Gemfile中添加了#gem 'github-pages'，这会将site.safe设置为true，导致无法加载_plugins下的*.rb了。

Jekyll templates

Use Liquid as templates engine by default.

Syntax like

Jekyll markdown processor

Use kramdown by default.

Fix building error

Found error mapping values are not allowed in this context at line 3 column 17

+jekyll build
Configuration file: /tmp/jgd-Luj/clone/_config.yml
            Source: /tmp/jgd-Luj/clone
       Destination: /tmp/jgd-Luj/clone/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
             Error: could not read file /tmp/jgd-Luj/clone/_posts/2018-04-03-typeerror-cannot-read-property-location-of-null.md: (<unknown>): mapping values are not allowed in this context at line 3 column 17
File /tmp/jgd-Luj/clone/uml/f9c0a3f22b87ac41771ecda270f82089.svg created (1667 bytes)
File /tmp/jgd-Luj/clone/uml/bd34b857a013c553afe9611a19e06bce.svg created (5021 bytes)
                    done in 9.812 seconds.

Change

title: TypeError: Cannot read property '_location' of null

to

title: "TypeError: Cannot read property '_location' of null"

Put all pages in “_pages” folder

See https://github.com/jekyll/jekyll/issues/920#issuecomment-63093764

  1. Modify _config.yml
include: ['_pages']
  1. Create _pages folder, create a file under it with the front matter:
---
permalink: /ava.html
title: ava
layout: page
---

See also

References