wǒ_is神仙

Using Jekyll with GitHub Pages

我不喜欢,也不擅长码字,我只是喜欢折腾。

去年我用 Octopress,慢慢发现,除了我自己为它写的插件,其他插件基本没用上。So,我为什么不直接用 Jekyll 呢,还省了静态化的过程,这种琐事直接交给 GitHub 得了。而且也不需要另建分支备份源码了,一举两得啊!

为了方便 You & Me,我弄了个小工具jekyll-cli <iframe src="http://ghbtns.com/github-btn.html?user={"buildrevision"=>"9b9ad2e603ace558b8a21e86e28568a5d761f58e", "pagesenv"=>"dotcom", "versions"=>{"jekyll"=>"1.5.1", "kramdown"=>"1.3.1", "liquid"=>"2.5.5", "maruku"=>"0.7.0", "rdiscount"=>"2.1.7", "redcarpet"=>"2.3.0", "RedCloth"=>"4.2.9", "jemoji"=>"0.1.0", "jekyll-mentions"=>"0.0.6", "jekyll-redirect-from"=>"0.3.1", "github-pages"=>"17", "ruby"=>"2.1.1"}, "projecttitle"=>"MrZhang.me", "projecttagline"=>"It's my blog. Welcome to", "ownername"=>"jsw0528", "ownerurl"=>"https://github.com/jsw0528", "ownergravatarurl"=>"https://github.com/jsw0528.png", "repositoryurl"=>"https://github.com/jsw0528/MrZhang.me", "repositorynwo"=>"jsw0528/MrZhang.me", "repositoryname"=>"MrZhang.me", "zipurl"=>"https://github.com/jsw0528/MrZhang.me/zipball/gh-pages", "tarurl"=>"https://github.com/jsw0528/MrZhang.me/tarball/gh-pages", "cloneurl"=>"https://github.com/jsw0528/MrZhang.me.git", "releasesurl"=>"https://github.com/jsw0528/MrZhang.me/releases", "issuesurl"=>"https://github.com/jsw0528/MrZhang.me/issues", "wikiurl"=>nil, "language"=>"CSS", "isuserpage"=>nil, "isprojectpage"=>true, "show_downloads"=>true, "url"=>"http://mrzhang.me"}&repo=jekyll-cli&type=fork&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="82" height="20">,跑在 NodeJS 上。接下来我就以jekyll-cli为引,简单介绍下如何使用 GitHub 原生支持的 Jekyll。

在本地创建一个 Jekyll 项目

Jekyll 是跑在 Ruby 上的,所以你得先确保你机子已经能跑 Ruby。最好 Bundler 也装好了:

$ gem install bundler

接着jekyll-cli上场,新建项目很简单:

$ jkl new path/to/blog

这样,在你指定的地方会创建一个名为blog的文件夹,里面包含了 Jekyll 所需的基本目录结构:

|-- _config.yml
|-- _layouts/
|   |-- default.html
|   `-- post.html
|-- _posts/
|   |-- 2013-03-21-hello-world.md
`-- Gemfile
`-- index.html

执行jkl new命令后会自动执行bundle install,如果想稍后手动安装 gems,请使用:

$ jkl new path/to/blog --no-bundle

创建文章

_posts/ 目录是存放文章源文件的地方,你可以按照约定格式YEAR-MONTH-DAY-title.MARKUP手动创建文件,或者使用jekyll-cli

$ cd path/to/blog
$ jkl post '文章标题'

你可以指定文件后缀名:

$ jkl post '文章标题' --ext html

或者作为草稿(Jekyll v1.x 新增功能):

$ jkl post '文章标题' --drafts

本地预览

$ jkl watch

默认端口号是4000,当然你可以在_config.yml中设置port: 8080,或者直接使用命令行:

$ jkl watch --port 8080

默认情况下,render posts 的时候,会把_drafts/目录内的草稿也包含进去,但你可以手动排除:

$ jkl watch --no-drafts

jekyll-cli有个贴心功能,就是使用默认浏览器自动打开本地预览地址:

$ jkl watch --open

本地服务跑起来之后,Jekyll 会自动创建_site/目录,把blog/目录内不是以下划线开头的文件(夹)全部 Copy 进来,Markdown 文件也会编译成 HTML。

预编译 Sass

我喜欢 Sass,所以jekyll-cli也就有了这个功能。命令就是:

$ jkl sass

设计博客外观的时候,Sass 文件频繁改动,希望能自动执行编译操作,使用:

$ jkl sass --watch

编译时使用的参数,可以在_config.yml中设置,具体有哪些参数可用,可以在终端执行compass help compile查看。写在_config.yml内的参数的格式跟终端显示的有一些区别,就是:去掉--前缀,然后把连字符-改成下划线_,如果没有参数值的,用布尔值truefalse代替。

连接 GitHub

在 GitHub 上新建一个仓库,然后在终端执行:

$ jkl git

终端会提示你输入具有读写权限的仓库地址,示例地址见下图:

部署

$ jkl deploy

该命令会将blog/目录内的文件(夹)push 到你刚刚创建的仓库中。本地预览时生成的_site/目录是不需要的,建议写进.gitignore

写在最后

jekyll-cli的命令,除了jkl new,其他都需要在blog/目录内执行。

更多命令可以运行jkl -h查看。列出某个命令所有 options,使用jkl [command] -h,比如jkl post -h

本文只是简单介绍,想要更深入的使用 Jekyll,需要你自己看文档

你可以为你的博客绑定自己的域名,还可以自定义404页面。想要了解更多,Github Pages 有详细的帮助文档

上面说的这些,应该不难吧?有什么没有表达清楚的地方么?你也可以研究下我博客的源码 <iframe src="http://ghbtns.com/github-btn.html?user={"buildrevision"=>"9b9ad2e603ace558b8a21e86e28568a5d761f58e", "pagesenv"=>"dotcom", "versions"=>{"jekyll"=>"1.5.1", "kramdown"=>"1.3.1", "liquid"=>"2.5.5", "maruku"=>"0.7.0", "rdiscount"=>"2.1.7", "redcarpet"=>"2.3.0", "RedCloth"=>"4.2.9", "jemoji"=>"0.1.0", "jekyll-mentions"=>"0.0.6", "jekyll-redirect-from"=>"0.3.1", "github-pages"=>"17", "ruby"=>"2.1.1"}, "projecttitle"=>"MrZhang.me", "projecttagline"=>"It's my blog. Welcome to", "ownername"=>"jsw0528", "ownerurl"=>"https://github.com/jsw0528", "ownergravatarurl"=>"https://github.com/jsw0528.png", "repositoryurl"=>"https://github.com/jsw0528/MrZhang.me", "repositorynwo"=>"jsw0528/MrZhang.me", "repositoryname"=>"MrZhang.me", "zipurl"=>"https://github.com/jsw0528/MrZhang.me/zipball/gh-pages", "tarurl"=>"https://github.com/jsw0528/MrZhang.me/tarball/gh-pages", "cloneurl"=>"https://github.com/jsw0528/MrZhang.me.git", "releasesurl"=>"https://github.com/jsw0528/MrZhang.me/releases", "issuesurl"=>"https://github.com/jsw0528/MrZhang.me/issues", "wikiurl"=>nil, "language"=>"CSS", "isuserpage"=>nil, "isprojectpage"=>true, "show_downloads"=>true, "url"=>"http://mrzhang.me"}&repo=MrZhang.me&type=fork&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="82" height="20">,或许可以给你一点点的帮助。

有任何疑问和心得,欢迎留言交流。