Jex’s Note

使用 Octopress 寫 Blog

介紹

一個寫 blog 的 framework, 使用 markdown 語法快速的記下筆記, 再利用 generate 指令幫你生成 html, 你可以 deploy 到 github, 直接使用 github 當作你的 host, 就不需要自己再去找主機架設了, 並且使用 git 做版控, 未來要搬家到其他支援 markdown 語法的服務都非常方便, 也不怕文章遺失問題, 唯一缺點就是有點使用門檻

目前最新版本是 3.0

運作原理

source 存放著主程式,當 generate 時會產生在 /public 下,如果執行 preview 其實是看到這資料夾底下的檔案

當執行 deploy 時,會將原本的 _deploy 刪除,並將 /public 資料 copy 為 _deploy 並且 push 到 master

所以 github 上的 master 就是你的 _deploy 資料夾,在這資料夾外面,包含根目錄等等都是 source

而你輸入 example.github.io 就會連到 example.github.iomaster branch

Octopress 3.0

Install

gem install octopress

New a blog

octopress new en.jex.tw

[Config] Modify _config.yml

  • title
  • email
  • description
  • url
  • github_username

[Deploy] Deploy github page as your host.

I already had a website on github, so I use another repository as this demonstration.

1) Set host where will deploy to

octopress deploy init git git@github.com:jex-lin/en

Octopress 3.0 supports two ways to let you deploy to host, which are github and s3.

2) Since I use github page so I need to change git_branch from master to gh-pages

It will generate a file _deploy.yml for deploy config.

3) Git init and commit. And Set remote branch

git init
git add .
git commit -m "First commit"
git remote add origin git@github.com:jex-lin/en.git

4) Build & deploy

jekyll build             # It will create `_site`.
octopress deploy         # It will copy `_site` to `.deploy` and push `.deploy` to remote branch `gh-pages`

5) Done! You will see that jex-lin.github.io/en works!

[Source] Push source to source remote for the first time

Remember to add .deploy to .gitignore before you push.

Your current branch may be master, rename to source and push to github

git branch -m source
git push origin source

[Deploy] Custom domain

1) Add a DNS record: (CNAME) en -> jex-lin.github.io

2) Create CNAME : echo "en.jex.tw" > CNAME

3) Build and deploy. You will see that en.jex.tw works.

[Config] Change url path (Recommended)

The default url path is like this /jekyll/update/2017/01/08/welcome-to-jekyll.html.

The categories defined in your post will be created as a folder when you build.

categories: jekyll update

So your url path will seem very long. Let’s change it shorter.

_config.yml :

permalink: /:title/

or octopress 2.0 default :

permalink: /blog/:year/:month/:day/:title/

[Command] Create a new post

You must be at the root path, because it will create _post and post file on your current path.

octopress new post "writing"

[Command] Preview

jekyll serve

localhost:4000

Octopress 2.0

Install

git clone git://github.com/imathis/octopress.git octopress
bundle install
rake install        安裝預設主題

bundle 指令 - 要先有 rvm 安裝 ruby 及 gem,再使用 gem 安裝 bundler 才能使用,安裝 gem 可參考此篇前半部

[Deploy] 佈署到Github上

[1] 到Github點選New Repository, Repository name 輸入 jex-lin.github.com

[2] 輸入指令

rake setup_github_pages    ( 輸入 git@github.com:jex-lin/jex-lin.github.com.git
rake generate
rake deploy                ( push到Github

[3] 檢查是否成功, 到 github 提供的網域 (ex: https://jex-lin.github.io/)

[Deploy] 新增文章及 push 到 github

因為 deploy 只會 push generate 出來的前端靜態檔, 但文章檔案還是在本機的, 所以要自動手動 push

git add .
git commit -m "First commit"
git push origin source

[Deploy] 在其他電腦部署己存在的 octopress

git clone -b source git@github.com:jex-lin/jex-lin.github.com.git octopress
cd octopress
bundle install          (才能使用 rake new_post['xxx'] 指令)
git clone git@github.com:jex-lin/jex-lin.github.com.git _deploy
rake generate
rake deploy

[Deploy] 同步不同電腦的 octopress

git pull                    ( 只會同步 _deploy
git pull origin source      ( 同步 source/_post

[Deploy] 將 Domain 指向 github page

新增一筆新的 DNS record : CNAME, subdomain: blog 指到 jex-lin.github.io

新增 CNAME 檔案在 source 目錄下

cd source
echo "blog.jex.tw" > CNAME

[Command] 建立文章

rake new_post['article_title']

會產生 .markdown 的檔案, BLOG內容直接打在虛線下面

[Command] 轉成網頁檔

rake generate

[Command] 預覽發佈

rake preview

輸入完指令打開瀏覽器網址列輸入 http://127.0.0.1:4000/

[Command] 發佈到網站

rake deploy

[Command] generate + deploy

rake gen_deploy

[Theme] 安裝主題

git submodule add git://github.com/octopress-themes/classic-light.git .themes/light
rake install[light]
rake generate
rake deploy

[Theme] 移除主題

1) 刪除 .gitmodules

[submodule ".themes/dark"]
  path = .themes/dark
  url = https://github.com/octopress-themes/classic-dark.git

2) 刪除 .git/config

[submodule ".themes/dark"]
  url = https://github.com/octopress-themes/classic-dark.git

刪除 theme files

git rm  --cached .themes/dark

[Layout] Remove sidebar

_config.yml:

  1. 註解 default_asides (# default_asides: [custom/asides/about.html, ...)
  2. 加上 sidebar: collapse

[Layout] 補充 : layout 對應的檔案路徑

  • navigation (Blog / Archieve) 那條的連結 : _includes/custom/navigation.html
  • 右邊關於我 (A little something about me.) : _includes/custom/asides/about.html,但會被 load 主要是在 _config.yml 中設定的 default_asides: [custom/asides/about.html, ..

[Layout] 在 navigation 新增 about me

1) octopress/source/_includes/custom/navigation.html :

<li><a href="/about">About me</a></li>

2) rake new_page["about"]

會產生 source/about/index.markdown

[Layout] 在側欄增加大頭像

1) 將圖片放到 octopress/source/images/about_me/sidebar.jpg

2) octopress/source/_includes/custom/asides/about.html :

<section>
    <h1>Jex</h1>
    <img alt="me" src="/images/about_me/sidebar.jpg">
    <p>Backend Engineer</p>
</section>

_config.yml :

default_asides: [custom/asides/about.html, ...(略)...]

[Config] 修改網站標題及描述

修改 _config.yml, 記得要 generatedeploy 才會生效

[Config] GA

_config.yml :

google_analytics_tracking_id: UA-23414877-5

[Troubleshooting] 如果 deploy 後接到 github 的錯誤信關於 theme 有問題

The page build failed with the following error:

The submodule `.themes/justin-kelly-theme` was not properly initialized with a `.gitmodules` file. For more information, see https://help.github.com/articles/page-build-failed-missing-submodule.

For information on troubleshooting Jekyll see:

  https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can contact us by replying to this email.

有可能是你的 master (_deploy 的個資料夾)的 .themes 跟你的 source 的 .themes 不一樣,建議刪除 _deploy/.themes 再 copy .themes 過去

[Troubleshooting] 如果你安裝 3.0 後,使用 octopress command 發生錯誤

/Users/jex/.rvm/rubies/ruby-2.3.0/lib/ruby/2.3.0/rubygems/specification.rb:2158:in `method_missing': undefined method `this' for #<Gem::Specification:0x3ff51a403e78 mercenary-0.3.6> (NoMethodError)

表示你需要升級你的 gem 了 :

gem install rubygems-update
update_rubygems
gem update --system

How to create multiple github pages?

First of all, let’s learn about how it works.

By default, http://jex-lin.github.io will point to master branch of jex-lin.github.io.

jex-lin.github.io/{repository_name} will point to gh-pages branch of this repository if it’s available.

Get started

  1. Create a new repository and name en as a example.
  2. Create file index.html in master and push to github, but website won’t be activated in master. So you need to rename from master to gh-pages.
  3. Then you will see that http://jex-lin.github.io/en/ is available in Settings page. ( If you had pointed to, it would be like this: http://blog.jex.tw/en/)

How to point en.jex.tw to http://jex-lin.github.io/en/ ?

  1. Add a record to your DNS. CNAME en -> jex-lin.github.io
  2. Create CNAME file and put en.jex.tw into it.
  3. Then you will see that en.jex.tw works.

Comments