文章

jekyll-安装

发表于 更新于
作者 echoCourage 13 分钟阅读 阅读次数:

关于jekyll

Jekyll使用Ruby脚本根据模板生成静态网页，实现了内容与排版的分离。

模板以嵌入Liquid脚本的HTML格式存放。内容为markdown或者html。


jekyll主题的目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

./
├── Gemfile
├── Gemfile.lock
├── LICENSE
├── README.md
├── _config.yml
├── _config.yml.default
├── _data/
├── _includes/
├── _javascript/
├── _layouts/
├── _plugins/
├── _posts/
├── _sass/
├── _site/
├── _tabs/
├── assets/
├── docs/
├── index.html
├── jekyll-theme-chirpy.gemspec
├── package.json
├── rollup.config.js
└── tools/

主题(当前使用主题): jekyll-theme-chirpy
==================================================================================
Gemfile：如果你使用 Bundler 管理 Ruby 依赖，
会列出所有的 gem 依赖，包括 Jekyll 本身和任何插件。


_config.yml： Jekyll 的配置文件
1. 用于指定网站的全局配置选项，例如网站标题、描述、基础URL、默认布局等。
2. 置文件中的选项可以被网站的其他文件引用，以便在生成网站时进行定制和配置

_posts  博客内容
文件名通常遵循 YEAR-MONTH-DAY-title.MARKUP 的命名规则

_pages  其他需要生成的网页，如About页

_layouts：网页排版模板
1. 存放网站的布局模板文件，这些模板定义了不同页面的结构和外观，例如文章页面、首页、标签页面等。
2. 布局模板文件通常使用 Liquid 模板语言编写，它允许你使用变量、条件语句和循环来动态生成页面内容。
3. 在页面的 Front Matter 中通过 layout: default 这样的声明来指定使用哪个布局模板

_includes：被模板包含的HTML片段，可在_config.yml中修改位置
1. 该目录用于存放可重用的页面片段或组件，例如页眉、页脚、导航菜单等。
2. 这些页面片段可以在布局模板中被包含或引用，以便在不同页面中重复使用。
 3. 通过 {% include file.ext %} 标签可以将这些部分包含到布局或页面中 

assets：辅助资源 css布局 js脚本 图片等
1. 存放网站的静态资源文件，例如图片、JavaScript 文件、样式表（非 Sass 格式）、字体文件等。
2. 这些静态资源可以在布局模板或页面中直接引用，以便在网站中显示或使用

_data 动态数据
1. 存放 YAML、JSON 或 CSV 格式的数据文件
2. 在网站的任何地方使用
3. Jekyll 会自动加载这些文件，并可以通过 site.data 访问这些数据

_sites  最终生成的静态网页

_sass：存放 SASS/SCSS 文件
Jekyll 会自动处理这些文件，并将它们编译成 CSS

jekyll-目录结构说明-表格

文件/文件夹 说明
_config.yml 存储配置数据。这些配置中的许多选项都可以从命令行中指定，但在这里指定它们更加容易，并且你不必记住它们
_drafts 草稿是未发布的文章。这些文件的命名格式是没有日期的：title.MARKUP。了解如何使用草稿。
_includes 这些是你的布局和帖子可以混合和匹配的部分，以促进重用。液体标签 {% include file.ext %} 可以用来包括在_includes/file.ext。
_layouts 这些是包装文章的模板。在YAML Front Matter 中逐层选择布局，这将在下一节中介绍。 The liquid tag {{ content }} 用于将内容注入网页。
_posts 可以这么说，这里是你的动态内容。这些文件的命名约定很重要，并且必须遵循以下格式：YEAR-MONTH-DAY-title.MARKUP。可以为每篇文章指定固定链接，但日期和MARKUP语言完全由文件名决定。
_data 格式良好的网站数据应该放在这里。Jekyll引擎将自动加载该目录中的所有数据文件（使用.yml，.yaml，.json或 .csv格式和扩展名），并且可以通过 site.data访问它们。如果目录下有文件 members.yml，则可以通过site.data.members访问该文件的内容。
_sass 是可以导入到 main.scss 中的sass部分，然后将它们处理成一个样式表 main.css ，该样式表定义了你的网站使用的样式。
_site 这是Jekyll完成转换后，生成的网站将被存放的（默认）位置。建议将它添加到 .gitignore 文件中。
.jekyll-metadata 临时文件，这些将帮助Jekyll追踪自上次构建站点后哪些文件未被修改，以及哪些文件需要在下一个版本中重新生成。该文件不会包含在生成的网站中。建议将它添加到.gitignore文件中。
index.*或其他HTML、md 假设该文件具有YAML Front Matter部分，它将由Jekyll进行转换。网站根目录中的任何.html，.markdown，.md 或 .textile 文件或上面未列出的目录也会发生同样的情况。
其他文件/文件夹 除了上面列出之外的其他文件夹和文件（例如css和images文件夹，favicon.ico文件等），将会被逐字复制到生成的网站中。如果你想知道它们是如何布置的，有很多网站已经在使用Jekyll。

工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

在项目文件夹(含有_config.yml)中运行jekyll build 指令后，jekyll会依次做如下几件事

 1. 加载_layout文件夹内的所有模板，并将其中的{% include xxxx.html %} 字段按照_includes文件夹内对应文件填入 

2.遍历_post文件夹及子文件夹，对所有命名符合yyyy-mm-dd-title.md 格式的博客文件放入 site.posts 变量(按时间倒序)，并对其进行解析，根据Front Matter 头的内容套入layout生成对应title的博客

3. 遍历整个项目子目录，扫描所有含Front Matter 头的文件，放入site.pages 变量并根据permalink 字段指定的URL目标位置生成index.html

 4. 在生成过程中，文件中包含的Liquid脚本 {{ content }} 会被解析并替换。Liquid指令包括Object、Tag、Filter三类，其中 

4.1 object是变量，在解析过程中会被直接文本替换，如
 {{ page.title }} 
	
4.2 Tag是控制流，可以做判断和循环，如

 {% if user %} 
       Hello {{ user.name }}! 
 {% else %} 
     {% assign foo = false %} 
     {{ foo }} 
 {% endif %} 

 {% if foo!= true %} 
  This statement is valid.
 {% endif %} 

 {% for product in collection.products %} 
     {{ product.title }} 
 {% endfor %} 


4.3 Filter用于对文本进一步处理

 {{ "fold" | | prepend: {{ site.baseurl }} | append: "/.html" }} 
 {{ "adam!" | capitalize | prepend: "Hello " }} 
Output: Hello Adam!


安装至MacOS

安装jekyll

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 依赖:
brew


# 安装: chruby 和 ruby-install
brew install chruby ruby-install xz
    ## 安装之后记得执行 安装过程中提示 source、export的内容
    source /usr/local/opt/chruby/share/chruby/chruby.sh
    source /usr/local/opt/chruby/share/chruby/auto.sh


# 最新的 Ruby 稳定版本
ruby-install ruby 3.1.3
    ## 在安装过程中有的可能需要访问外网，设置http代理即可
    ## 安装过程中会有大量的编译过程，持续大概5-10min
    ## 遇到保存请看下面，<<安装中遇到的问题>>

# 配置.bash_profile
echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.bash_profile
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.bash_profile
echo "chruby ruby-3.1.3" >> ~/.bash_profile # run 'chruby' to see actual version
source ~/.bash_profile


# 查看 ruby的版本
ruby -v
    # 应该显示 ruby 3.1.3p185（2022-11-24 修订版 1a6b16756e）或更高版本

# 安装最新的 jekyll
gem install jekyll

安装中遇到的问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

1. 执行: ruby-install ruby 3.1.3
报错日志
=======================================================================
...
...
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/evp.h:565:56: note: expanded from macro 'EVP_MD_CTX_get_size'
# define EVP_MD_CTX_get_size(e)        EVP_MD_get_size(EVP_MD_CTX_get0_md(e))
                                                       ^
./openssl_missing.h:219:35: note: expanded from macro 'EVP_MD_CTX_get0_md'
#  define EVP_MD_CTX_get0_md(ctx) EVP_MD_CTX_md(ctx)
                                  ^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/evp.h:554:1: note: 'EVP_MD_CTX_md' has been explicitly marked deprecated here
OSSL_DEPRECATEDIN_3_0
^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/macros.h:193:49: note: expanded from macro 'OSSL_DEPRECATEDIN_3_0'
#   define OSSL_DEPRECATEDIN_3_0                OSSL_DEPRECATED(3.0)
                                                ^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/macros.h:62:52: note: expanded from macro 'OSSL_DEPRECATED'
#     define OSSL_DEPRECATED(since) __attribute__((deprecated))
                                                   ^
ossl_digest.c:262:40: warning: 'EVP_MD_CTX_md' is deprecated [-Wdeprecated-declarations]
    return rb_str_new_cstr(EVP_MD_name(EVP_MD_CTX_get0_md(ctx)));
                                       ^
./openssl_missing.h:219:35: note: expanded from macro 'EVP_MD_CTX_get0_md'
#  define EVP_MD_CTX_get0_md(ctx) EVP_MD_CTX_md(ctx)
                                  ^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/evp.h:554:1: note: 'EVP_MD_CTX_md' has been explicitly marked deprecated here
OSSL_DEPRECATEDIN_3_0
...
...

1 warning generated.
compiling ossl_ts.c
In file included from ossl_ts.c:10:
In file included from ./ossl.h:171:
./openssl_missing.h:195:11: warning: 'TS_VERIFY_CTS_set_certs' macro redefined [-Wmacro-redefined]
#  define TS_VERIFY_CTS_set_certs(ctx, crts) ((ctx)->certs=(crts))
          ^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/ts.h:426:11: note: previous definition is here
#  define TS_VERIFY_CTS_set_certs(ctx, cert) TS_VERIFY_CTX_set_certs(ctx,cert)
          ^
ossl_ts.c:829:5: error: incomplete definition of type 'struct TS_verify_ctx'
    TS_VERIFY_CTX_set_certs(ctx, x509inter);
    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
./openssl_missing.h:215:46: note: expanded from macro 'TS_VERIFY_CTX_set_certs'
#  define TS_VERIFY_CTX_set_certs(ctx, crts) TS_VERIFY_CTS_set_certs(ctx, crts)
                                             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
./openssl_missing.h:195:52: note: expanded from macro 'TS_VERIFY_CTS_set_certs'
#  define TS_VERIFY_CTS_set_certs(ctx, crts) ((ctx)->certs=(crts))
                                              ~~~~~^
/usr/local/Cellar/openssl@3/3.1.2/include/openssl/ts.h:407:16: note: forward declaration of 'struct TS_verify_ctx'
typedef struct TS_verify_ctx TS_VERIFY_CTX;
               ^
1 warning and 1 error generated.
make[2]: *** [ossl_ts.o] Error 1
make[1]: *** [ext/openssl/all] Error 2
make: *** [build-ext] Error 2
!!! Compiling ruby 3.1.3 failed!
=======================================================================
原因: 可能是在编译过程中安装了一些其他依赖，但是没有source、export

解决: 
1. 执行编制过程中安装的依赖提示的 source、export
2. 报错内容是提示openssl版本不兼容的问题，根据查找资料，安装openssl1.1版本及需要安装的依赖: (记得source、export 提示内容)
    brew install openssl readline zlib libyaml
    brew cleanup openssl@1.1

2. 继续重新运行: ruby-install ruby 3.1.3
提示安装成功:
=======================================================================
...
...
installing bundled gems:            /Users/fengshao/.rubies/ruby-3.1.3/lib/ruby/gems/3.1.0
                                    minitest 5.15.0
                                    power_assert 2.0.1
                                    rake 13.0.6
                                    test-unit 3.5.3
                                    rexml 3.2.5
                                    rss 0.2.9
                                    net-ftp 0.1.3
                                    net-imap 0.2.3
                                    net-pop 0.1.1
                                    net-smtp 0.3.1
                                    matrix 0.4.2
                                    prime 0.1.2
                                    rbs 2.7.0
Building native extensions. This could take a while...
                                    typeprof 0.21.3
                                    debug 1.6.3
Building native extensions. This could take a while...
installing bundled gem cache:       /Users/fengshao/.rubies/ruby-3.1.3/lib/ruby/gems/3.1.0/cache
>>> Successfully installed ruby 3.1.3 into /Users/fengshao/.rubies/ruby-3.1.3
=======================================================================
项目部署, jekyll
项目部署 jekyll
本文由作者按照 CC BY 4.0 进行授权