使用 Jekyll 构建你的网站 - 初入门

文章目录

一、Jekyll介绍

Jekyll 是一个开源的静态网站生成器,支持 Markdown 和 HTML 两种文件类型,其中 HTML 使用了 Liquid 模板语言。

你可以使用 Markdown 编写内容,使用 HTML/CSS 来构建和展示,Jekyll 会将其编译为静态的 HTML。

Jekyll 使用 Ruby 引擎将用 Markdown 编写的文章转换成 HTML。

官网:

二、Jekyll安装和启动

Jekyll 网站 提供了 Linux、MacOS 和 Windows 安装说明。可点击跳转到官网查看

一般情况下,我们会将Jekyll项目拉取到本地,编写,调试,然后再推送到仓库上。

那么,我们有必要了解下如何在本地调试Jekyll项目。

2.1 配置Ruby环境

1)Windows

在 Windows 下配置 Ruby 环境,安装 RubyInstaller 即可。

RubyInstaller 是一个基于 Windows 的安装程序,包括了 Ruby、运行环境等。

RubyInstaller Downloads下载 Ruby+Devkit,选择推荐版本,使用默认配置安装。

安装完成之后,CMD 中输入 ruby -v 或者 gem -v,有输出版本即代表安装成功。

2)macOS

在 macOS Big Sur 11.x 版本下就已经自带了 Ruby 环境。

如果是以前版本的 macOS,使用 Homebrew 便可以安装 Ruby:brew install ruby。

同样的,在 macOS 下也可以使用 RubyGems 管理 Ruby 软件包。

2.2 安装 Jekyll

有了 Ruby 环境以及 RubyGems 就可以安装 Jekyll。

在命令行输入如下命令安装Jekyll:gem install jekyll

安装之后,输入 jekyll -v 检查是否安装成功。

2.3 构建Jekyll项目

注意:下文将讲述如何使用GitLink平台一键构建及部署Jekyll项目。

创建一个全新的工程,执行如下命令:

bash 复制代码
jekyll new learn-jekyll

执行完成之后,我们就成功创建了一个名为 learn-jekyll 的 Jekyll 项目。

2.4 启动 Jekyll 服务

Jekyll 环境搭建完成之后,进入到项目目录下(有 _config.yml 文件的目录),

输入启动命令:jekyll serve 或者 jekyll s。

若没有异常,启动服务后的默认端口为 4000,浏览器地址栏输入 localhost:4000 即可访问。

启动服务时使用命令:jekyll s --drafts,可以同时访问草稿(_drafts)目录下的文章。

三、Jekyll常用命令

安装完 Jekyll 之后,系统环境中就有了 jekyll 这个可执行的命令, 这里列举几个常用命令:

  • jekyll new PATH - 创建新项目
  • jekyll new PATH --blank - 创建新的空项目
  • jekyll build 或 jekyll b - 构建项目,生成可部署的 _site 目录
  • jekyll serve 或 jekyll s - 构建并运行项目,会自动监听文件变化,不需要反复执行
  • jekyll clean - 清除所有的构建产物
  • jekyll new-theme - 创建一个新的主题脚手架
  • jekyll doctor - 诊断,输出所有已经废弃的依赖包或者有问题的配置

四、目录结构

4.1 主要目录

一般情况下,Jekyll项目构建完成后,包括如下文件和文件夹:

  • _posts: 用于存放博客文章。
  • _site: 用于存放项目构建完成之后所生成的静态文件,也就是说,静态网站的所有文件都会来源于此,其中 CSS 文件、JS 文件以及图片文件,会存放在该目录下的 assets 文件夹中。我们可以直接把该目录下的文件拿去部署。
  • about.markdown: "关于页"的内容。在执行构建时会被转化成 html 文件,放置于 _site 目录下。
  • index.markdown: "主页"的内容。在执行构建时会被转化成 html 文件,放置于 _site 目录下。
  • 404.html: "404 页"的内容。
  • _config.yml: Jekyll 的全站配置文件,一些全局配置会写在这个文件内,比如 collections,默认文件/路径,等等。总之,这里可以自定义很多东西
  • .gitignore: 创建项目时会自动生成,不需要纳入到 CVS 的文件存放于此
  • Gemfile& Gemfile.lock 存放项目所依赖的 Ruby gems

4.2 其他的约定目录

除了上面提到的几个目录,我们还可以添加其它的,Jekyll 会自动识别出它们,执行相应的处理。

_data - 网站所需要的数据文件(相当于一个小型数据库)

_drafts - 博客草稿,不会被构建成静态文件,也不会公开

_layouts - 布局文件,相当于一类页面(比如博客类页面)的"父类"

_includes - 小模块,属于 HTML 文件的一部分,可以在多个页面中复用,比如导航(navigation)、脚注(footer)等

五、使用GitLink构建Jekyll博客

5.1 生成Jekyll项目

我们也可以使用GitLink平台直接新建一个Jekyll项目。

GitLink平台内置了多个模板,大家可以选择自己喜欢的模板进行构建。

同时,GitLink平台支持一键部署Jekyll项目,解决大家购买服务器,手动部署的困扰。

前提条件
第一步:登录GitLink平台(https://www.gitlink.org.cn/login)
第二步:进入设置>个人建站>我的站点

如果用户未完成实名认证审核,将提示"您尚未通过实名认证,无法使用此服务,如需使用,请先进行实名认证。", 可点击"前往验证"完成实名认证。

第三步:新建站点


第四步:去仓部进行部署
第五步:编写项目代码,完成初次部署及访问

5.2 本地编写Jekyll博客内容

上面操作,我们已经基于GitLink新建了一个带有模板的Jekyll项目。

5.2.1 clone仓库

我们可以clone仓库到本地,编写博客内容。

我们clone的仓库代码如下图所示:

5.2.2 本地调试

注意:如果调试中遇到困难,可能先搜索网上可靠解决方法。 如果无法解决,推荐跳过该步骤,直接在GitLink平台部署。

由于项目是哟Gemfile管理依赖,我们可以使用命令一键安装依赖包:bundle install

Bundle命令详解:

bash 复制代码
# 显示所有的依赖包 
$ bundle show
 
# 显示指定gem包的安装位置 
$ bundle show [gemname]
 
# 检查系统中缺少那些项目依赖的gem包 
# 注:如果系统中存在所有项目依赖的包,则会输出:The Gemfile's dependencies are satisfied 
$ bundle check
 
# 安装项目依赖的所有gem包 
# 注:此命令会尝试更新系统中已存在的gem包 
$ bundle install
 
# 安装指定的gem包 
$ bundle install [gemname]
 
# 更新系统中存在的项目依赖包,并同时更新项目Gemfile.lock文件 
$ bundle update
 
# 更新系统中指定的gem包信息,并同时更新项目Gemfile.lock中指定的包信息 
$ bundle update [gemname]
 
# 向项目中添加新的gem包引用 
$ gem [gemname], [ver]
 
# 你还可以指定包依赖关系 
$ gem [gemname], :require => [dependence_gemname]
 
# 你甚至还可以指定gem包的git源 
$ gem [gemname], :git => [git_source_url]
 
# 锁定当前环境 
# 可以使用bundle lock来锁定当前环境,这样便不能通过bundle update来更新依赖包的版本,保证了统一的环境 
$ bundle lock
 
# 解除锁定 
$ bundle unlock
 
# 打包当装环境 
# bundle package会把当前所有信赖的包都放到 ./vendor/cache/ 目录下,发布时可用来保证包版本的一致性。 
$ bundle package

如果我们不基于Gemfile安装依赖,直接启动Jekyll服务, 可能会由于未安装依赖包遇到如下错误raise_not_found!': Could not find gem 'xxx' in locally installed gems. (Bundler::GemNotFound) ,只需要使用 gem对缺失的依赖包进行安装即可。

bundler版本与锁定不一致,导致的报错:

其他类似的版本问题解决法方法一致。

  1. 修改Gemfile.lock中的版本为你电脑已安装的版本
  2. 重新执行bundle install
  3. 再尝试启动服务:jekyll s
5.3.3 创建一篇文章

创建文章很简单。你需要做的就是在 _post 目录下使用正确的格式和扩展名创建一个新文件,这样就完成了。

5.3.3.1 文章文件名

Jekyll 要求一篇文章的文件名遵循下面的格式: 年-月-日-标题.MARKUP

在这里,年是 4 位数字,月和日都是 2 位数字。MARKUP扩展名代表了这篇文章是用什么格式写的。下面是一些合法的文件名的例子:

bash 复制代码
2011-12-31-new-years-eve-is-awesome.md
bash 复制代码
2012-09-12-how-to-write-a-blog.textile
5.3.3.2 文章文件内容

所有博客文章顶部必须有一段 YAML 头信息(YAML front- matter)。

在它下面,就可以选择你喜欢的格式来写文章。

Jekyll 支持 Markdown,以及其他众多格式的扩展,其中就包括十分流行的 Textile。

这些格式都有自己的方式来标记文章中不同类型的内容,所以你首先需要熟悉这些格式并选择一种最符合你需求的。

下面是参考

markup 复制代码
---
layout: post
title: "Welcome to Jekyll!"     # 文章标题
date:  2021-08-29 11:28:12 +0530
categories: jekyll update
---

这部分是文章的具体内容,可以自定义编写。
5.3.3.3 示例

下面是我写的文章参考:

文件名:2023-12-25-API自动化测试框架.markdown

markup 复制代码
---
layout: post
title:  "使用 Jekyll 构建你的网站 -> 初入门"
date:   2023-12-25 13:54:58 +0800
categories: jekyll update
---

## 一、Jekyll介绍
Jekyll 是一个开源的静态网站生成器,支持 Markdown 和 HTML 两种文件类型,其中 HTML 使用了 Liquid 模板语言。
你可以使用 Markdown 编写内容,使用 HTML/CSS 来构建和展示,Jekyll 会将其编译为静态的 HTML。
Jekyll 使用 Ruby 引擎将用 Markdown 编写的文章转换成 HTML。

官网:
- https://jekyllrb.com/docs/
- https://jekyllcn.com/docs/home/

渲染后的效果如下所示:

  • 首页

  • 文章详情

5.3 推送文章到仓库

上面我们已经编辑好博客的内容,我们就可以将本地编辑好的内容推送到仓库,使用GitLink平台实现一键部署。

git推送命令参考:

bash 复制代码
git add .
git commit -m "commit信息"
git push

5.4 一键部署启动

进入Jekyll项目对应的仓库,找到"服务>个人建站" ,进入页面。

点击"去部署"按钮,重新部署。

部署成功后,就可以访问博客主页啦~

相关推荐
MengYiKeNan14 天前
github pages 的 workflow 突然运行失败
github·github pages
RobinDevNotes25 天前
用VuePress在GitHub Pages上搭建博客
vue·github pages·vuepress
北桥苏7 个月前
Hexo最新实战:(一)Hexo7.0+GitHub Pages博客搭建
github·hexo·github pages
_长银10 个月前
Ubuntu20.04 安装jekyll
ubuntu20.04·jekyll
Huazie1 年前
【实操】基于 GitHub Pages + Hexo 搭建个人博客
hexo·github pages·个人博客搭建
soulteary1 年前
改善 GitHub Pages 阅读体验:Quick Docs
docker·github·github pages
AiENG_071 年前
创建Github Pages 仓库
html·github·github pages·静态站
欧雷殿1 年前
聊下我这豆瓣化改造后的网站
前端·架构·jekyll
死神6541 年前
2023年最新 Github Pages 使用手册
前端·github·github pages