Installation

该文档描述了本地撰写该项目所需要安装的软件以及在不同平台下的安装步骤。开始安装的时候可能需要一些时间来进行配置。

如果安装过程中出现任何问题,可以在QQ群中提出来,我们可以一起研究、解决并更新文档,让安装更便捷。

Requirements


我们需要一些软件来支持该环境的运行

在非Windows平台上运行jekyll

相对来说,在Windows平台搭建环境难度要大一些,并且没有官方的说明文档,所以我们接下来着重介绍Windows平台下环境的jekyll的安装过程,其它平台的安装请查看这里

安装RubyGems


安装Jekyll最好的方式就是通过RubyGems安装,在Windows下最佳方案是利用Rails来安装Ruby以及Ruby所需的工具包。

  • 首先下载RailsInstaller
  • 在选择optional Tasks时勾选(Install Git)和(Add executables for Ruby, DevKit and Git to the PATH)选项
  • 安装完毕后,Rails会提进行Git配置,输入相应用户名和邮箱即可
  • 在终端执行$ ruby -v来查看是否安装成功,安装成功会返回ruby的具体版本信息

更改Gem源


Ruby的默认Gem Sources为http://rubygems.org/,而该源部署在Amazon S3上,由于国内网络原因访问非常不稳定,所以需要更换源,执行以下命令来替换Ruby的默认源:

$ gem sources --remove http://rubygems.org/
$ gem sources -a http://ruby.taobao.org

终端输入$ gem sources -l查看默认源是否替换成功,成功则显示为:

*** CURRENT SOURCES ***
http://ruby.taobao.org/

安装Jekyll


该项目采用Jekyll转换器,可以将多种标签的标记语言转换成最终的HTML文档格式并在GitHub编译运行。为了在本地测试所编写的文档,需要在本地安装Jekyll。

利用gems进行jekyll的安装,具体命令如下,$ jekyll -v查看是否安装成功

$ gem install jekyll
$ gem install rdiscount kramdown wdm

安装Python


Jekyll转换器使用了pygments实现对多种程序代码类型的格式转换及上色支持,Jekyll默认支持Pygments的版本为0.5.0,但是在安装rails的时候自带的版本是0.5.4,并且部分Dependencies也没有安装,所以需要重新安装pygments及其dependencies。

Pygments支持easy_install安装,而easy_install是用Python编写的脚本工具,所以为了安装Pygments需要先安装Python。

  • 下载并安装Python
  • 安装后在系统环境变量PATH中配置Python相关的环境变量
  • $ python -V查看是否安装并配置成功(注意:是大写的-V)
  • easy_install实际上是setupTools里面的一个子工具,我们需要安装SetupTools来包含easy_install工具
  • 下载脚本ez_setup.py至本地,例如D盘根目录
  • 终端执行$ python d:/ez_setup.py进行SetupTools的安装

在运行的时候会发生一个错误,该错误为

ascii codec can't decode byte 0xe8 
in position 0:ordinal not in range(128)

大意为ascii编码不能解析byte 0xe8。解决方法:找到并打开python根目录/Lib/mimetypes.py文件,在import urllib后,添加代码:

reload(sys)
sys.setdefaultencoding('gbk')

把默认编码方式改为gbk(网上有写用utf8的,在这个脚本中是无效的,需要改成gbk格式)。重新执行$ python d:/ez_setup.py,如果出现刷屏的安装信息,则说明安装成功了。此时,在python目录下多了一个Script文件夹,easy_install就在里面。

执行$ gem list来查看pygments版本,如果没有执行

C:\Python27\Scripts> easy_install.exe Pygments

如果存在pygments,并且版本不为"0.5.0"接下来更改Pygments的版本:

$ gem uninstall pygments.rb --version "=0.5.4"
$ gem install pygments.rb --version "=0.5.0"

执行$ gem list来查看pygments版本是否更换为0.5.0

至此,Windows平台上基本环境的搭建就完成了。
接下来会具体讲解如何应用GitHub来获取最新的项目和文档。


comments powered by Disqus
Tech Materials