Jekyll 笔记

Jekyll 相关资源整理


Windows 安装 Jekyll

MacOS 安装

  • MacOS 已集成主要环境可以直接安装

文件夹安装

已安装 Bundler 直接执行 bundle update jekyll 或者bundle update

未安装 Bundler 先安装 gem update jekyll

全局安装

sudo gem install bundler
sudo gem install -n /usr/local/bin/ jekyll

查看当前版本

bash jekyll -v

升级 jekyll

  • 升级前请先查看相关文档:- jeykll 升级:Upgrading - jekyllrb
  • 确认所需的 ruby 版本 ruby -v
  • 知晓版本中的功能变更,一般会有参数修改或者删除一些老的用法。

未安装 bundle ,先安装 bundle

gem update jekyll

已安装 bundle

bundle update jekyll

安装指定版本 示例,请勿直接使用

gem install bundler:2.1.4

如果无法安装或者一直报错可以看一下已安装版本和卸载低版本

gem uninstall bundler

再安装最新版本

gem install bundler 

参考资料

环境搭建

jekyll new myblog 全新安装

Install the jekyll and bundler gems. 安装 jekyll 和 bundler gems

gem install jekyll bundler

Create a new Jekyll site at ./myblog. 创建一个新的 jekyll 站点,会在当前目录下新建一个文件夹

jekyll new myblog

Change into your new directory. 进入对应文件夹

cd myblog

运行本地服务

bundle exec jekyll serve

clone 安装 本地编译并运行

建议先从 gitlab 或者 github clone 或者 fork 一个仓库

初次运行需要先安装

bundle install

已经安装后

bundle exec jekyll server

本地生成静态 HTML 和对应资源文件

bundle exec jekyll build -d _site

ruby3.0 运行 jekyll 报错

无法加载 webrick

------------------------------------------------
      Jekyll 4.2.0   Please append `--trace` to the `serve` command 
      for any additional information or backtrace. 
------------------------------------------------
/Users/username/.rvm/gems/ruby-2.7.0/gems/jekyll-4.2.0/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError)

执行命令,给 Gemfile 文件添加 webrick 配置

bundle add webrick

执行成功后会在 Gemfile 文件尾端增加一行 gem "webrick", "~> 1.7"(2021-01-18) 解决方法:https://github.com/jekyll/jekyll/issues/8523

说明

/_site 静态文件生成目录,一般 .gitignore 文件中要注明这个目录 /photo 不含下划线的文件夹中的文件都会处理成 page 或者直接复制到生成目录 /index.html 主页文件,也可以用 index.md

YEAR-MONTH-DAY-title.md 文章命名规范

exclude: [DIR, FILE, ...] 忽略文件,不会被 jekyll 处理(这些目录文件不会生成,无法访问) include: [DIR, FILE, ...] 强制处理,如 .htaccess(如果该文件被忽略,会强行生成) timezone: TIMEZONE 时区 encoding : utf-8 编码 permalink: /:categories/:year/:month/:day/:title.html 文章 URL 定制

paginate: 5 分页数 paginate_path: "blog/page:num/" 分页 URL 路径

模板

  • Jekyll Cheat Sheet 参数表(含代码示例):https://cloudcannon.com/community/jekyll-cheat-sheet/
  • Liquid User Guide For J1 Theme: https://jekyll.one/pages/public/manuals/liquid/user_guide/

输出全部页面(页面导航)

  • site.pages 全部页面,整个jekyll 的全部页面
  • site.url 假设 url 是一个 collections,那只会调用该 collections 的全部页面链接
{% for my_page in site.pages %}
  {% if my_page.title %}
  <a class="page-link" href="{{ my_page.url | prepend: site.baseurl }}">{{ my_page.title }}</a>
  {% endif %}
{% endfor %}

按分类输出该各分类下所有内容

{% for category in site.categories %}
<h2>{{ category | first }}</h2>
</span>{{ category | last | size }}</span>
<ul class="arc-list">
    {% for post in category.last %}
        <li>{{ post.date | date:"%d/%m/%Y"}}<a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
</ul>
{% endfor %}

仅输出全部分类(不含链接)

{% for category in site.categories %}
<h2>{{ category | first }}</h2>
<span>{{ category | last | size }}</span>
{% endfor %}

输出全部标签(标签云)

href 的值结合自己 jekyll 实际设定调整

{% for tag in site.tags %}
    {% assign count = tag | last | size %}
    {% assign fontsize = count | times: 4 %}
    {% if count  > 2 %}
    <a class="post-tags-item" href="/tag/{{ tag | first }}/" title="{{ tag | first }}" data-count="{{ count }}" style="font-size: {% if fontsize > 24 %}24{% else %}{{ fontsize }}{% endif %}px">{{ tag | first }}</a>
    {% endif %}
{% endfor %}

注释掉页面代码或内容 {% comment %}

使用 {% comment %} 注释掉的模板代码或内容,在生成的时候不会输出,所以在html网页源代码中看到这部分内容。

{% comment %}
要被注释的内容
{% endcomment %}

slug

如果页面没有配置,默认使用文件名(:title)

引入模板文件

head.html 也可以是 style.css 样式文件或者更多“文本类型”文件。

{% include head.html %}

include 验证支持的文件格式

  • html
  • css
  • md

通过 front matter 或 _data 使用 include 和 include_relative

通过 front matter 或 _data 中的 csv 或 yml 读取配置

通过 front matter 配置 include_relative

---
css_link: page.css
---
{% include_relative {{page.css_link}} %}

通过 _data 中的 csv 或 yml 配置 include

product.yml

pic: 
url: images/001.jpg

front matter

---
css_link: pic
---
{% assign product = site.data.[page.project_name] %}
{% include {{product.url}} %}

md文件避免执行liquid代码片段导致报错

当我们在文字中分享liquid代码片段时,jekyll生成的时候可能会报错,按以下方式处理

{% raw %}
``` 
// 原来代码片段 (包括开头结尾的 ```)
``` 
{% endraw %}

查看参考:https://github.com/jekyll/jekyll/edit/master/docs/_docs/datafiles.md

YAML 使用技巧

单独调用 YAML 指定的一个参数的值

_data/test.yml 内容

name:
  id1: john
  id2: lola

test.html 内容

<p>ID1 的 name: {{site.data.test.name.id1}}</p>
<p>ID2 的 name: {{site.data.test.name.id2}}</p>

include 语句或 include 文件中使用页面变量

---
title: My page
my_variable: footer_company_a.html
---
{% if page.my_variable %}
  {% include {{ page.my_variable }} %}
{% endif %}

include 参数传递到包括的结构

假设 _includes/note.html 包含此段代码。

在页面引用 note.html 时配置 content ,{{ include.content }} 内容会被填充为指定内容。

<div class="header">
<h2>Note:</h2>
{{ include.content }}
</div>
{% include note.html content="This is my sample note." %}

配置多个参数,假设 _includes/header_logo.html 包含此段代码。

<figure>
   <a href="{{ include.url }}">
   <img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
      alt="{{ include.alt }}"/>
   </a>
   <figcaption>{{ include.caption }}</figcaption>
</figure>
{% include header_logo.html url="https://1px.run"
max-width="200px" file="logo.png" alt="Jekyll logo"
caption="This is the Jekyll logo." %}

include 参数传递变量而不是字符串

{% capture download_note %}
The latest version of {{ site.product_name }} is now available.
{% endcapture %}

省略参数内容前后的引号,因为它不再是字符串而是变量。

{% include note.html content=download_note %}

assign 创建变量重复使用

{% assign text_read = "已读" %}
{{ text_read }}

capture 指定内容重复使用

{% capture text_read %}已读{% endcapture %}

{{ text_read }}

{{ text_read }}编译后显示已读,支持单行也支持多行

include_relative 引用当前文件目录下的文件 相对路径链接

假设这个代码片段存在 page/home.html,会引用 page/tpl/footer.html 该个路径文件。

{% include_relative tpl/footer.html %}

include 相关文档

通过文章、页面头信息访问yml数据中指定内容

可以用于语言设定 _data/language.yml

en:
    name: English
    doname: en
cn:
    name: 中文
    doname: cn

language_cn.html 页面内容

---
title: 中文语言
language: cn
---

{% assign language = site.data.language[page.language] %}
<a rel="language"
  href="https://{{ language.doname }}.1px.run"
  title="{{ language.name }}">
    {{ language.name }}
</a>

yml数据中全部内容

language_all.html 页面内容

---
title: 全语言
---
<ul>
{% for language in site.data.sago.update_popups_language %}
{% assign update = language[1] %}
  <li>
    <a rel="language"
      href="https://{{ language.doname }}.1px.run"
      title="{{ language.name }}">
        {{ language.name }}
    </a>
  </li>
{% endfor %}
</ul>

操作符

基本判断运算

操作符说明
==等于
!=不等于
>大于
<小于
>=大于等于
<=小于等于
or或者
and和,并且
contains字符串包含
startswith字符串开头
endswith字符串结尾

操作符 一个 if 判断多个运算条件

{% if item.tag != 'error' and item.sort != 'note' %}
 tag 不包括 error 和 note 的内容
{% endif %}

使用 else 实现不包含 not contains

{% if item.tag contains 'error' %}
{% else %}
  tag 不包括 error 的内容
{% endif %}

使用 unless 实现不包含 not contains

(未验证)

{% if item.tag %}
  {% unless item.tag contains "error"
    tag 不包括 error 的内容
  {% unless item.tag contains "error"
    tag 不包括 error 的内容
  {% endunless %}
{% endif %}

数据类型

类型值或说明演示
空值null
Booleantruefalse{% assign foo = true %}
Number{% assign my_int = 30 %} {% assign my_float = 88.76 %}
String引号包裹字符串{% assign my_string = "Hello Atop!" %}
Nil类似 undefined
Array索引取值{{ site.users[0] }} {{ site.users[1] }}
Array遍历操作{% for user in site.users %} {{ user }} {% endfor %}

条件判断

值的判断

{% if post.wrong == null %}
  - 无数据
{% elsif post.wrong == 'on' %}
  ON
{% else %}
  {{ post.wrong }}
{% endif %}

读取 YAML(YML 或 JSON 或 CSV) 数据时通过类型筛选 参考文档(jekyllrb)

<ul>
{% for item in site.data.help %}
  {% if item.category == 'coins' %}
  <li>
    {{ item.title }}
  </li>
  {% endif %}
{% endfor %}
</ul>

读取 YAML(YML 或 JSON 或 CSV) 数据时排序 参考文档(jekyllrb)

{% assign doclist = site.data.samplelist.docs | sort: 'title'  %}
<ol>
{% for item in doclist %}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ol>
  • 更多条件判断案例:
    • https://www.scube.co/guide/liquid-cheatsheet/
    • https://shopify.dev/docs/api/liquid/basics

排序

排序方式演示代码
升序{% assign event = site.data.event_list | sort: "date" %}
降序{% assign event = site.data.event_list | sort: "date" | reverse %}
两个排序方式?{{ site.pages | sort: "title", "last" }}

strip_html 删除字符串中html标记

输入

{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

输出

Have you read Ulysses?

newline_to_br 换行符转为html代码<br>

newline_to_br 让内容输出时按换行符进行换行

{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | newline_to_br }}

输出效果

<br />
Hello<br />
there<br />

strip_newlines 删除字符串中换行符

从字符串中删除任何换行符(换行符)。

输入

{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | strip_newlines }}

输出

Hellothere

remove 移除字符串中指定内容

输入

{{ "I strained to see the train through the rain" | remove: "rain" }}

输出

I sted to see the t through the 

remove_first 移除字符串中指定内容只操作一次

输入

{{ "I strained to see the train through the rain" | remove_first: "rain" }}

输出

I sted to see the train through the rain

prepend 指定内容前插入内容

在字符串前面插入内容

输入

{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}

输出

Some fruit: apples, oranges, and bananas
prepend can also accept a variable as its argument.

输入

{% assign url = "example.com" %}
{{ "/index.html" | prepend: url }}

Output

example.com/index.html

replace 替换内容中指定的内容

替换指定内容

输入

{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}

输出

Take your protein pills and put your helmet on

replace_first 只替换一次内容中的指定内容

替换指定内容,但是只执行一次

输入


{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}

输出

Take your protein pills and put my helmet on

reverse 反转数值或字符串中内容

反转数组中项目的顺序。reverse不能反转字符串。

输入

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}

{{ my_array | reverse | join: ", " }}

输出

plums, peaches, oranges, apples

虽然reverse不能直接在字符串上使用,但您可以将字符串拆分为数组,反转数组,然后通过将过滤器链接在一起重新加入。

输入

{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

输出

.moT rojaM ot lortnoc dnuorG

last 提取数值或字符串中最后的内容

返回数组的最后一项。

输入

{{ "Ground control to Major Tom." | split: " " | last }}

输出

Tom.

输入

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}

{{ my_array.last }}

输出

tiger

last当您需要在标签内使用过滤器时,可以使用点表示法:

{% if my_array.last == "tiger" %}
  There goes a tiger!
{% endif %}

url_decode 将 URL 编码字符转为字符串

解码已编码为 URL 或由url_encode.

输入

{{ "%27Stop%21%27+said+Fred" | url_decode }}

输出

'Stop!' said Fred

url_encode 将字符串转为 URL 编码字符

将字符串中的任何 URL 不安全字符转换为百分比编码字符。

输入

{{ "john@liquid.com" | url_encode }}

输出

john%40liquid.com

请注意,这url_encode会将空格变成+符号而不是百分比编码的字符。

输入

{{ "Tetsuro Takara" | url_encode }}

输出

Tetsuro+Takara

upcase 将字符串中的英文字母转为大写

使字符串中的每个字符大写。它对已经全部大写的字符串没有影响。

输入

{{ "Parker Moore" | upcase }}

输出

PARKER MOORE

downcase 将字符串中 英文字母转为小写

输入

{{ "Parker Moore" | downcase }}

输出

parker moore

truncatewords 按单词截断字符串内容并添加自定义省略符号

将字符串缩短为作为参数传递的字数。如果指定的单词数小于字符串中的单词数,则将省略号 (…) 附加到字符串。

输入

{{ "Ground control to Major Tom." | truncatewords: 3 }}

输出

Ground control to...

truncate 按字符串字符截断

输入

{{ "Ground control to Major Tom." | truncate: 20 }}

输出

Ground control to...

数值计算

加法

{{ 183.357 | plus: 12 }}

195.357

minus 减法

{{ 183.357 | minus: 12 }}

171.357

times 乘法

---
number1: 5
number3: 10
---
{{ 5 | times: 10 }}
{{ page.number1 | times: page.number2 }}

两者结果均为50

divided_by 除法

默认四舍五入 输入

{{ 20 | divided_by: 7 }}

输出

2

这是一个浮点数:

输入

{{ 20 | divided_by: 7.0 }}

输出

2.857142857142857

生成相对路径链接或者绝对路径链接

相对路径链接

{{ "/assets/style.css" | relative_url }}

/my-baseurl/assets/style.css

绝对路径链接

{{ "/assets/style.css" | absolute_url }}

http://example.com/my-baseurl/assets/style.css

自定义省略号

truncatewords接受一个可选的第二个参数,该参数指定要附加到截断字符串的字符序列。默认情况下,这是一个省略号 (…),但您可以指定不同的序列。

输入

{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}

输出

Ground control to--

自定义日期格式

https://shopify.github.io/liquid/filters/date/

将时间戳转换为另一种日期格式。此语法的格式与 strftime. 输入使用与 Ruby 相同的格式Time.parse

输入

{{ article.published_at | date: "%a, %b %d, %y" }}

输出

Fri, Jul 17, 15

输入

{{ article.published_at | date: "%Y" }}

输出

2024

date如果字符串包含格式正确的日期,则适用于字符串。

输入

{{ "March 14, 2016" | date: "%b %d, %y" }}

输出

Mar 14, 16

要获取当前时间,请将特殊单词”now”(或”today”)传递给date。

输入

This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

输出

This page was last updated at 2024-03-11 16:24.

请注意,该值将是上次从模板生成页面的当前时间,而不是当涉及缓存或静态站点生成时将页面呈现给用户的时间。

date_to_string 将日期转为短格式

{{ site.time | date_to_string }}

07 Nov 2008

以美国序数形式将日期转为字符串

将日期格式化为序数、美国、短格式。


{{ site.time | date_to_string: "ordinal", "US" }}

Nov 7th, 2008

无法比较数据或计算输出内容

假设我只输出 view 数据大于等于 500 的内容。

正确操作方式:

{% assign view = item.view | plus: 0 %}
{% if view >= 500 %}
  内容
{% endif %}

错误举例:

由于无法进行子变量比较,所以如果子变量大于小于的数字计算会报错,提示不能用字符串计算

{% if item.view >= 500 %}
  内容
{% endif %}

Liquid 报错提示

 Liquid Exception: Liquid error (line 128): comparison of String with 500 failed in project/lanshu/home.html

参考:Liquid error: comparison of String with ‘number’

collections 功能 (集合)

使用演示

_config.yml 配置

collections:
  url:
    output: true
    permalink: /:collection/:name/ #生成的链接形式
defaults:
  - scope:
      path: ""
      type: "url" # 指定一个类型
    values: # 页面头部信息,比如 layout、tag 等,也可以添加模板的自定义字段
      layout: touch # 该类型使用的模板 layout
      page_width: 960px # 自定义字段

_layouts/url.html 模板

---
layout: default
---
<div class="page">
  <h1 class="mt-4 publication-title">{{ page.title }}</h1>
  <div class="publication-authors">{{ page.authors }}</div>
  <div class="publication-info">{{ page.publication }}, {{ page.year}}</div>
  <div class="publication-teaser">
    <img
      src="/images/publication-pages/{{ page.slug }}.jpg"
      alt="project teaser"
    />
  </div>
  {{ content }}
  <h2 id="downloads">Downloads</h2>
  <p>
    <a href="/download/{{ page.slug }}.pdf"
      ><i class="far fa-file-pdf"></i> PDF</a
    >&nbsp;&nbsp; {% if page.slides %}
    <a href="/download/{{ page.slug }}_slides.pdf"
      ><i class="far fa-file-pdf"></i> Slides</a
    >&nbsp;&nbsp; {% endif %}
    <a href="/download/{{ page.slug }}.bib"
      ><i class="far fa-file-alt"></i> BibTex</a
    >&nbsp;&nbsp; {% if page.doi %}
    <a href="{{ page.doi }}"><i class="fas fa-external-link-alt"></i> DOI</a
    >&nbsp;&nbsp; {% endif %}
  </p>
</div>

列表页

---
layout: 
title: Url
permalink: /url/
---
<h1 class="mt-4">Publications</h1>
{% assign publications = site.url | sort: "year" | reverse %}
{% for pub in publications %}
<div class="pubitem">
  <div class="pubtitle">{{ pub.title }}</div>
  <div class="pubauthors">{{ pub.authors }}</div>
  <div class="pubinfo">{{ pub.publication }}, {{ pub.year}}</div>
  <a href="{{pub.url}}"><i class="fas fa-link"></i> Project Page</a>
</div>
{% endfor %}

内容页 _url/mypub19.md

文件存放路径 _url/mypub19.md (文件夹名称必须使用_开头)

---
title: A New Method for Fancy Research
authors: John Doe and Mary Jane
publication: Journal of Fancy Research
year: 2019
doi: http://dx.doi.org/XX.XXX/
---
8888

内容页 _url/mypub18.md

---
title: 什么
authors: 这个
publication: 什么情况
year: 2019
doi: http://dx.doi.org/XX.XXX/
---
6666

通过页内 front matter 的 YAML 列表输出在页面列表中

front matter 部分

---
list:
  - title: Happy
    description: are you happy?
  - title: Apple
    description: i like your apple tree.
  - title: Nice Day
    description: hello world.
---

内容部分

<div class="list-grid">
{% for my_log in page.list %}
  <div class="item">
    <p>{{ my_log.title }}</p>
    <p>Description: {{ my_log.description }}</p>
  </div>
{% endfor %}
</div>

标签功能实现,自动生成标签页面

列表页分页说明

  • 分页功能
    • 分页的路径是固定的如第2页:blog/page2/index.html,但是不会生成page1这个文件夹
    • 使用了 permalink 就不能使用分页功能
    • 分页功能只支持 html 文件
    • 不支持对分类、标签页分页

文章摘要调用和手动切割摘要的分隔符

在列表调用文章摘要内容:post.excerpt

在配置文件自定义切割摘要的分隔符:excerpt_separator: <!--more-->

模板构建

参考内容

48 个你需要知道的 Jekyll 使用技巧 https://crispgm.com/page/48-tips-for-jekyll-you-should-know.html

静态博客目录生成方案选择 https://weiweitop.fun/2020/03/18/%E9%9D%99%E6%80%81%E5%8D%9A%E5%AE%A2%E7%9B%AE%E5%BD%95%E7%94%9F%E6%88%90%E6%96%B9%E6%A1%88%E9%80%89%E6%8B%A9/

48 个你需要知道的 Jekyll 使用技巧 https://crispgm.com/page/48-tips-for-jekyll-you-should-know.html

jekyll - 如何使用Liquid列出目录中的文件? - Stack Overrun https://stackoverrun.com/cn/q/4750500

让 html 模板可以识别和解析 Markdown

{% capture markdown_content %}

## 天气预报

- [天气预报 天气网](https://m.weather.com.cn/)
- [天气预报 weather.com](https://weather.com/weather/today/)
- [天气网 The Weather Network](https://www.theweathernetwork.com/)


{% endcapture %}

{{ markdown_content | markdownify }}

Liquid

让 jekyll 支持解析 .txt 中的 Markdown

新建 markdownify.html 文件,存于 _layouts 文件夹: _layouts/markdownify.html

文件内容如下,请将 layout 替换你常用的模板,比如layout: post

---
layout: page
---
{{ content | markdownify }}
  1. 在 .txt 格式的Markdown文件使用 markdownify.html 模板
  2. permalink 后面必须加上 .html 不然生成的是 txt 文件,如果使用类似 /page/ 目录路径 就要这样写 /page/index.html
  3. 保存后构建或者运行服务,访问 http://127.0.0.1:4000/txtdomo/ 查看效果(请替换自己的域名和端口)

layout: markdownify title: Markdown 预览 permalink: /txtdomo/index.html —

这个方式除了可以支持 .txt 还可以支持其他后缀。

因为部分软件无法识别 .md 所以会把文件夹命名为 .md.txt ,在电脑端使用 vscode的时候会做格式匹配,在手机上,txt格式基本都能支持

你的页面内容

  • 终于可以支持 .txt 后缀的Markdown文件渲染了 ```

模板优化

获取文字字数和阅读所需时间

<div class="post-meta">
    <span>本文共 {{ page.content | strip_html | strip_newlines | remove: " " | size }} 字 <b>·</b> 阅读大约需要 {{ page.content | strip_html | strip_newlines | remove: " " | size | divided_by: 350 | plus: 1 }} 分钟</span>
</div>

相关链接

模板和功能小窍门


回到顶部

Copyright © 2017-2024 1px.run (像素教程) Distributed by an MIT license.

Site updated at 2024-04-23 12:45