ToDo

• 如何支持窄行距
• 缩进显示不正常
• git over https
• 支持中文文件名
• 支持svg文件

原理

• git是一个版本管理工具，完成版本的控制；
• github是基于github的一个应用，可识别markdown语法标记，并自动生成html；
• jekyll是一个基于ruby的静态html页面生成工具，可以增加插件，可识别markdown语法标记；

在 Windows 7 下安装必要的软件

• Octopress 在 git 中维护，需要安装 git

到 msysgit 查找下载最新版本
当前的最新版本 Git-1.7.9-preview20120201.exe，下载后直接安装

• Octopress/Jekyll 是 ruby 应用程序，需要安装 ruby

到 RailsInstaller 查找下载最新版本
Octopress 要求安装 rubyinstaller-1.9.2-p290
安装后，确保 C:\Ruby192\bin 在 Windows 当前用户的 PATH 环境变量中
ruby 的模块工具 gem 在生成本地模块时可能需要用到编译环境
有两种选择 MinGW and MSYS 或 RubyInstaller DevKit
本文选择 RubyInstaller 推荐的 RubyInstaller DevKit
下载 RubyInstaller DevKit
安装需执行如下步骤
将 DevKit 自解压包释放到 C:\DevKit
在 Windows CMD 窗口中执行 ruby dk.rb init
在 Windows CMD 窗口中执行 ruby dk.rb install

• jekyll/Octopress 使用 Python 编写的代码加亮系统 pygments，需要安装 python（可选）

到 ActiveState 下载 最新的 ActivePython-2.7 版
执行安装程序
在 Windows CMD 窗口中执行 easy_install pygments

软件安装后的 Windows 7 环境说明和配置

两种命令行环境
Windows 7 自己的 CMD窗口，用于输入 DOS 类命令
MINGW/Git Bash 窗口启动了 bash，可以输入 Linux 类命令
环境变量
在 Windows 的 “高级系统设置” 中设置的 环境变量 可以被 MINGW 窗口继承
设置 LANG 和 LC_ALL 两个环境变量，其值均设置为 zh_CN.UTF-8
在 CMD 窗口中测试： echo %LANG% %LC_ALL%
在 MINGW 窗口中测试： echo $LANG $LC_ALL
MINGW/Git Bash 窗口启动了 bash，可以使用 ~/.bash_profile 环境设置文件设置环境变量、命令别名等
$ echo “export LANG LC_ALL” > ~/.bash_profile
$ echo “alias ll=’ls -l —color=tty’” >> ~/.bash_profile
$ echo “alias ls=’ls —color=tty’” >> ~/.bash_profile
注意：若希望~/.bash_profile中的设置生效，请启动 MINGW/Git Bash 窗口，而不是Windows 的 CMD窗口

ruby 环境的初始配置

设置 gem 的更新源
gem sources —remove http://rubygems.org/
gem sources -a http://ruby.taobao.org/
gem sources -l # 请确保只有 http://ruby.taobao.org 一行输出

安装 rdoc 和 bundler
gem install rdoc bundler

安装 Octopress

1. 克隆 Octopress

   mkdir ~/repos  
   cd ~/repos  
   git clone git://github.com/imathis/octopress.git sinosmond.github.com  
   cd ~/repos/sinomsond.github.com  
   

2. 修改 Octopress 的 GEM 源
   vi Gemfile

   将行 ： source "http://rubygems.org/"  
   改为 ： source "http://ruby.taobao.org/"  
   

3. 安装 Octopress 所需的GEM组件

   bundle install  
   

4. 生成 Octopress 的模版文件

   $ rake install  
   

   如果出现以下提示：

   rake aborted!  
   You have already activated rake 0.9.2.2, but your Gemfile requires rake 0.9.2.  
   Using bundle exec may solve this.  
   (See full trace by running task with --trace)  
   

   解决方法:

   $ bundle update; rake install  
   

git 和 github

学习 git 参考
为啥 Git 最棒
git - 简易指南
git 魔法 – git
10篇写给Git初学者的最佳教程
学习 Github 参考
如何高效利用GitHub
GotGitHub
The GitHub Hep
设置本地仓库和远程仓库的关联

创建 github 账号和仓库
下面的操作假定您注册了 的账号
下面的操作假定您创建了 .github.com 的仓库
本例使用 sinosmond.github.com，请用 .github.com 替换之
在本地版本库中设置远程版本库的别名
$ git remote add myblog git@github.com:sinosmond/sinosmond.github.com.git

配置和使用 Octopress

Octopress 的基本配置

编辑 _config.yml 文件 ，根据您自己的需要修改其值, 参考
若文件中包括中文，则存成 UTF-8 编码格式

url:                # For rewriting urls for RSS, etc  
title:              # Used in the header and title tags  
subtitle:           # A description used in the header  
author:             # Your name, for RSS, Copyright, Metadata  
simple_search:      # Search engine for simple site search  
description:        # A default meta description for your site  
subscribe_rss:      # Url for your blog's feed, defauts to /atom.xml  
subscribe_email:    # Url to subscribe by email (service required)  
email:              # Email address for the RSS feed if you want it.  

编辑新页面

生成 BLOG/静态 页面
rake new_post[“article name”] : 生成指定的 Blog 初始页面
rake new_page[“page name”] : 生成指定的静态初始页面
使用你惯用的编辑器修改新生成的文件
使用 YAML 语法设置本页面属性，用 Markdown 语法书写文章内容
若文件中包括中文，则存成 UTF-8 编码格式
Markdown 语法说明
Markdown: Dingus 是一个在线转换工具
若使用 kramdown 解析器，参考 kramdown 语法
Markdown 和多种标记语言的在线转换
Markdown 多种实现的在线比较
首次提交到 Github

rake setup_github_pages ： 配置 octopress 与 github 的连接
rake generate ： 生成静态文件
rake preview ： 在本机4000端口生成访问内容
rake deploy ： 发布文件到 github
使用 rake 任务管理 BLOG

$ rake -T
rake clean # Clean out caches: .pygments-cache, .gist-c…
rake copydot[source,dest] # copy dot files for deployment
rake deploy # Default deploy task
rake gen_deploy # Generate website and deploy
rake generate # Generate jekyll site
rake install[theme] # Initial setup for Octopress: copies the de…
rake integrate # Move all stashed posts back into the posts…
rake isolate[filename] # Move all other posts than the one currentl…
rake list # list tasks
rake new_page[filename] # Create a new page in source/(filename)/ind…
rake new_post[title] # Begin a new post in source/_posts
rake preview # preview the site in a web browser
rake push # deploy public directory to github pages
rake rsync # Deploy website via rsync
rake set_root_dir[dir] # Update configurations to support publishin…
rake setup_github_pages[repo] # Set up _deploy folder and deploy branch fo…
rake update_source[theme] # Move source to source.old, install source …
rake update_style[theme] # Move sass to sass.old, install sass theme …
rake watch # Watch the site and regenerate when it changes

进一步配置 Octopress

配置 社会化网络 应用

选择您中意的网站注册，获得用户名或网络代码，将代码存入 source/_includes/{post,custom} 目录
类型 国外服务 国内服务
Feed烧制 FeedBurner FeedSky
分享到 AddThis JiaThis
微博 Twitter weibo.com
网络书签 Delicious, Google Bookmarks QQ书签, 百度搜藏
网络图床 Flickr yupoo , POCO
网络评论 Disqus 友言

配置侧栏

在 _config.yml 中指定显示内容和显示顺序
显示内容
系统默认的显示边栏的内容基于 source/_includes 目录保存为 asides/.html
用户自定义的边栏内容基于 source/_includes 目录保存为 custom/asides/.html
显示顺序
blog_index_asides 控制BLOG首页的边栏显示
post_asides 控制每一个单独的BLOG页面显示时的边栏（对应 rake new_post[]）
page_asides 控制静态页面显示时的边栏（对应 rake new_page[]）

blog_index_asides:  
- custom/asides/feeds.html  
- asides/recent_posts.html  
- custom/asides/recent_comments.html  
- custom/asides/opers.html  
- asides/github.html  
- asides/twitter.html  
- asides/delicious.html  
- asides/pinboard.html  
- asides/googleplus.html  
- custom/asides/weibo.html  
- custom/asides/copyleft.html  

post_asides:  
- asides/recent_posts.html  
- custom/asides/recent_comments.html  
- custom/asides/opers.html  
- custom/asides/copyleft.html  

page_asides:  
- asides/recent_posts.html  
- custom/asides/recent_comments.html  
- custom/asides/copyleft.html  

pandoc解析器

• 为octopress增加pandoc支持
  在octopress的gemfile中增加pandoc-ruby

• 为 Jekyll 装上瑞士军刀 Pandoc 经过测试可以成功，首先需要安装pandoc，然后安装pandoc-rub组件

  • 支持中文字符编码：

  • liquid error: incompatible character encodings: UTF-8 and GBK

    chcp 65001

  • 在参照Jekyll Quick Start一文对Jekyll进行安装和配置后，启动Jekyll –server时提示如下错误:Forbidden no access permission to /‘

    修改Jekyll读取文件时的默认编码，即将convertible.rb(去Jekyll安装目录里找吧)中的第29行（左右）由

    self.content = File.read(File.join(base, name))

    修改为

    self.content = File.read(File.join(base, name), :encoding => “utf-8”)

• pandoc可以解析数学公式如：

  $e^x = \sum{n=0}^\infty \frac{x^n}{n!} = \lim{n\rightarrow\infty} (1+x/n)^n$

  pandoc 语法

• 使用pandoc

在_config.yml增加以下内容：

markdown: pandoc
pandoc:
    extensions: [mathjax, standalone]  **注意缩进**

• 修改jekyll支持pandoc（markdown.rb）

增加以下内容(def setup以下)：

when 'pandoc'
begin
require 'pandoc-ruby'
# Load pandoc extensions
@pandoc_extensions = @config['pandoc']['extensions'].map { |e| e.to_sym }
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts '  $ [sudo] gem install pandoc-ruby'
raise FatalException.new("Missing dependency: pandoc-ruby")
end

增加以下内容(def convert(content)以下)：

when 'pandoc'
PandocRuby.new(content, *@pandoc_extensions).to_html

git push 避免密码提示

• 下载git-credential-winstore.exe
• 运行git-credential-winstore.exe
• 第一次提示时输入相应的用户名\密码
• 后续就不再提示用户名\密码输入了

新的环境配置

重新安装操作系统后，会涉及到jekyll的环境重新配置，jekyll的运行涉及以下几个模块，ruby、devkit、pandoc、git，在path路径中增加如下：

D:\OurInternet\Ruby192\bin;D:\OurInternet\devkit\bin;D:\OurInternet\Pandoc\bin;D:\OurInternet\Git\bin

页面目录结构插件

Indexer for Octopress实现页面目录结构

按正常方式配置无效，Troubleshooting可以实现

对indexer.rb jekyll:indexer#process修改如下：

idx ||= '#' + idx_raw
==》
idx = '#' + idx_raw

增加新浪微博分享插件

sina weibo plugin for Octopress

由于没有使用octopress自动框架，需要手动修改_layouts/post.html 和_layouts/page.html，使其包含custom/post/sharing.html

3D tag-cloud插件

安装完成，需要对其进行修改：

1. 避免和category_list冲突，修改命名为category_3D_cloud

   Liquid::Template.register_tag('category_cloud', Jekyll::CategoryCumulusCloud)    
   ==>
   Liquid::Template.register_tag('category_3D_cloud', Jekyll::CategoryCumulusCloud)    
   

2. 其原有的swf不支持中文显示，目前没有解决方案

文章分类插件

文章分类(对应categories)插件不使用octpress提供的，使用这个修改过的插件，避免和tag插件出现冲突。
在_config.yml增加:
default_asides:

#- custom/asides/category_list.html 
- custom/asides/category_cloud.html         

中文分类名问题解决：

1. plugin/category_generator.rb

   categories = categories.sort!.map do |item|
   "<a class='category' href='/#{dir}/#{item.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase}/'>#{item}</a>"
   ==>
   categories = categories.sort!.map do |item|
   "<a class='category' href='/#{dir}/#{item.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase}/index.html'>#{item}</a>"
   

2. plugin/category_list.rb

   url = category_dir + category.gsub(/_|\P{Word}/u, '-').gsub(/-{2,}/u, '-').downcase + '/index.html'
   ==>
   url = category_dir + category.gsub(/_|\P{Word}/u, '-').gsub(/-{2,}/u, '-').downcase + '/index.html'
   

文章标签插件

在 github 找到这种插件： robbyedwards / octopress-tag-pages和 robbyedwards / octopress-tag-cloud。前者负责采集文章的 tag 信息，后者提供标签云展示功能。

需要修改的几个地方：

1. 文件头tag—>tags

2. 中文标签名支持有问题，需要更改

   • plugin/tag_cloud.rb :

     slug = name.to_s.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase  
     @separator = "" if i == (weighted.size - 1)
     html << "#{@tag_before}<a style=\"font-size: #{size}#{unit}\" href=\"/#{dir}/#{slug}/\">#{name}</a>#{@separator}#{@tag_after}\n"
     ==>
     slug = name.to_s.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase + '/index.html' 
     @separator = "" if i == (weighted.size - 1)
     html << "#{@tag_before}<a style=\"font-size: #{size}#{unit}\" href=\"/#{dir}/#{slug}\">#{name}</a>#{@separator}#{@tag_after}\n"
     

   • plugin/tag_generate.rb:

     tags = tags.sort!.map do |item|
     "<a class='tag' href='/#{dir}/#{item.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase}/'>#{item}</a>"
     ==>
     tags = tags.sort!.map do |item|
     "<a class='tag' href='/#{dir}/#{item.gsub(/_|\P{Word}/, '-').gsub(/-{2,}/, '-').downcase}/index.html'>#{item}</a>"
     

   • jekyll/page.rb:

     def write(dest)
             path = destination(dest)
             FileUtils.mkdir_p(File.dirname(path))
             File.open(path, 'w') do |f|
                 f.write(self.output)
             end
     end
     ==>
     def write(dest)
         path = destination(dest)
         tp = File.join(dest, @dir)
         FileUtils.mkdir_p(tp)
         #    FileUtils.mkdir_p(File.dirname(path)) **dirname在分析utf-8字符串时出现错误，因此将其规避**
         File.open(path, 'w') do |f|
             f.write(self.output)
             end
     end
     

ditaa 插件

安装ditaa，该软件基于java，需要配置好java环境
jekyll-ditaa，分析其源程序，目前只支持linux系统，需要修改程序以便支持win32
存在的问题如下：

• 不支持windows
  原脚本不支持windows需要改造
• ditaa不支持中文
  通过命令行测试可以支持中文，但是输入中文后，排版出现问题
• 编码有问题
  写入的块数据，没有正常编码

辅助工具

更新管理源码的仓库分支

git add .  
git commit -m "add some changes"  
git push myblog source  

markdown编辑工具

• MarkDown使用手册
• MarkdownPad,初步使用后，专用vim编辑器。
• Markdown here一个chrome扩展,安装完成后，在gmail的新邮件编辑框里面直接按Markdown语法写作，完成后点鼠标右键即可翻译为html文档。
• Markdown 语法