jekyll Octopress (Archived)

介紹

一個寫 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.io 的 master branch

Octopress 3.0

Install

gem install octopress

New a blog

octopress new username.github.io

[Config] Modify `_config.yml`

title
email
description
url
github_username

[Deploy] Deploy github page as your host.

Set repo

octopress deploy init git git@github.com:username/username.github.io

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

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

Since using github page, change git_branch from master to gh-pages in _deploy.yml.

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

Git init and commit. And Set remote branch

git init git add . git commit -m “First commit” git remote add origin git@github.com:username/username.github.io.git
Build & deploy

jekyll build # It will create _site. octopress deploy # It will copy _site to .deploy and push .deploy to remote branch gh-pages
Done! You will see that username.github.io/username.github.io 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 add .
git commit -m "Second commit"
git push origin source

[Deploy] Custom domain

Add a DNS record: (CNAME) blog -> username.github.io
Create CNAME : echo "blog.example.com" > CNAME
Build and deploy. You will see that blog.example.com 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

Change theme

https://github.com/planetjekyll/awesome-jekyll-themes
google jekyll theme

Custom CSS

Create assets/main.scss and copy below:

---
---

@import "{{ site.theme }}";

/* custom css */
pre > code {
    font-family: Menlo;
}

jekyll build or serve will generate new css and replace _site/assets/main.css

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 輸入 username.github.com

[2] 輸入指令

rake setup_github_pages    ( 輸入 git@github.com:username/username.github.io.git
rake generate
rake deploy                ( push到Github

[3] 檢查是否成功, 到 github 提供的網域 (ex: https://username.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:username/username.github.com.git octopress
cd octopress
bundle install          (才能使用 rake new_post['xxx'] 指令)
git clone git@github.com:username/username.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 指到 username.github.io

新增 CNAME 檔案在 source 目錄下

cd source
echo "blog.example.com" > 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] 移除主題

刪除 .gitmodules

[submodule “.themes/dark”] path = .themes/dark url = https://github.com/octopress-themes/classic-dark.git
刪除 .git/config

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

刪除 theme files

git rm  --cached .themes/dark

_config.yml:

註解 default_asides (# default_asides: [custom/asides/about.html, ...)
加上 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, ..

octopress/source/_includes/custom/navigation.html :
rake new_page["about"]

會產生 source/about/index.markdown

[Layout] 在側欄增加大頭像

將圖片放到 octopress/source/images/about_me/sidebar.jpg
octopress/source/_includes/custom/asides/about.html :

_config.yml :

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

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

修改 _config.yml, 記得要 generate 及 deploy 才會生效

[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/test/.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?

By default, http://username.github.io will point to master branch of username.github.io.

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

Your first github page’s repo name has to be named username.github.io. You can name anything you want for second page’s repo name.

Create a new repository and name custom-name as a example.
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.
Then you will see that http://username.github.io/custom-name/ is available in Settings page.

How to point custom-name.example.com to http://username.github.io/custom-name/ ?

Add a record to your DNS. CNAME custom-name -> username.github.io
Create CNAME file and add custom-name.example.com.
Then you will see it custom-name.example.com works.

jekyll Octopress (Archived)

介紹

運作原理

Octopress 3.0

Install

[Config] Modify `_config.yml`

[Deploy] Deploy github page as your host.

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

[Deploy] Custom domain

[Config] Change url path (Recommended)

[Command] Create a new post

[Command] Preview

Change theme

Custom CSS

Octopress 2.0

Install

[Deploy] 佈署到Github上

[Deploy] 新增文章及 push 到 github

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

[Deploy] 同步不同電腦的 octopress

[Deploy] 將 Domain 指向 github page

[Command] 建立文章

[Command] 轉成網頁檔

[Command] 預覽發佈

[Command] 發佈到網站

[Command] generate + deploy

[Theme] 安裝主題

[Theme] 移除主題

[Layout] Remove sidebar

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

[Layout] 在 navigation 新增 about me

[Layout] 在側欄增加大頭像

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

[Config] GA

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

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

How to create multiple github pages?

介紹

運作原理

Octopress 3.0

Install

[Config] Modify _config.yml

[Deploy] Deploy github page as your host.

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

[Deploy] Custom domain

[Config] Change url path (Recommended)

[Command] Create a new post

[Command] Preview

Change theme

Custom CSS

Octopress 2.0

Install

[Deploy] 佈署到Github上

[Deploy] 新增文章及 push 到 github

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

[Deploy] 同步不同電腦的 octopress

[Deploy] 將 Domain 指向 github page

[Command] 建立文章

[Command] 轉成網頁檔

[Command] 預覽發佈

[Command] 發佈到網站

[Command] generate + deploy

[Theme] 安裝主題

[Theme] 移除主題

[Layout] Remove sidebar

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

[Layout] 在 navigation 新增 about me

[Layout] 在側欄增加大頭像

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

[Config] GA

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

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

How to create multiple github pages?

[Config] Modify `_config.yml`