Tạo một trang web Jekyll trên localhost

Nếu như bạn sử dụng Github PagesJekyll để tạo trang web như trang trang này, bạn sẽ muốn tạo một bản sao ở trên máy mình trước khi publish lên Github Pages. Bản sao này sẽ cho phép bạn xem trước các bài viết cũng như các thay đổi về giao diện.

Lý do là bởi các cache của trình duyệt update khá chậm mỗi khi có sự thay đổi. Nếu hai lần thay đổi cách nhau không lâu, trình duyệt sẽ không kịp nhận ra sự thay đổi ấy, bạn phải refresh lại trình duyệt rất nhiều lần thậm chí sử dụng các trình duyệt khác, chưa từng mở trang ấy để biết sự thay đổi đã xảy ra chưa. Điều này là quá phiền phức!

Tạo một bản sao trang web trên máy của bạn là một sự lựa chọn hoàn hảo. Ngoài ra đây còn là cách giúp bạn thiết kế giao diện hoặc làm mọi thứ với trang web Jekyll trước khi quyết định xuất bản nó.

Các câu lệnh Git, Bash dùng trong bài tôi soạn thảo trên Cmder. Bạn có thể dùng Git Bash hoặc Windows PowerShell hay bất kỳ trình Terminal nào thay thế cũng được.

1 Đầu tiên nhất bạn cần cài đặt Git trên máy của bạn. Ở đây tôi không nói chi tiết vì bài viết này tập trung vào việc khác.

Với Windows, bạn download và cài Git từ đây.

Với Linux (Debian/Ubuntu), bạn dùng câu lệnh sau:

sudo apt-get install git-all

Với Mac, bạn có thể download và cài từ đây.

Thông tin thêm và chi tiết có thể đọc ở đây.

2 Kế tiếp, bạn cần cài Bundler, ta cần cái này để có thể quản lý Ruby gems dependencies cho Jekyll, giảm thiểu lỗi khi chạy. Để có thể cài Bundler, bạn cần cài Ruby trước. Download và cài Ruby tại đây.

Sau đó check xem có cài Ruby thành công chưa (hoặc là đã có cài Ruby trên máy chưa):

ruby --version

Tiếp đến là cài Bundler:

gem install bundler

3 Tạo local repository cho local Jekyll site của bạn bằng cách di chuyển đến một thư mục chứa thư mục trang web của bạn, ví dụ GithubLocal (trong thư mục này có thể có nhiều thư mục con, mỗi thư mục là một local reposiroty chứa một trang web riêng).

git init jekyll-local-site-repo-name

# Một thư mục mới được tạo GithubLocal\jekyll-local-site-repo-name\
cd jekyll-local-site-repo-name

4 Tới đây bạn có thể chọn lựa là chạy site Jekyll trên nhánh chính master của repo hay là chạy trên nhánh phụ dựa án gh-pages. Nếu chọn master, bạn có thể bỏ qua bước này, nếu chọn gh-pages, bạn cần tạo nhánh đó bằng dòng lệnh:

git checkout -b gh-pages

5 Bây giờ đến phần quan trọng nhất, cài Jekyll bằng cách dùng Bundler. Bạn kiểm tra trong thư mục jekyll-local-site-repo-name xem đã có sẵn file Gemfile chưa (không có đuôi), nếu chưa thì bạn cần tạo một file như thế (không có đuôi) với nội dung như sau:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins

Sau đó gõ lệnh:

bundle install

Sau khi chạy hoàn tất, sẽ có thể một file Gemfil.lock được tạo ra.

Các lỗi phát sinh (nếu có)

Trong trường hợp bạn gặp lỗi, ví dụ như lỗi liên quan đến commonmaker: failed to build gem native extension, bạn làm như sau

  1. Check xem đã cài Msys2 chưa. Hoặc có thể download và cài lại cho chắc.
  2. Sau đó bạn cần cài lại Ruby, download ở đây. Cài một cách bình thường, tốt nhất là để mặc định.
  3. Cài thêm cả Ruby-Dev, download ở đây. Riêng Ruby-DevKit, file exe download về là một file giải nén, bạn nên giải nén vào thư mục dạng C:\RubyDevKit, sau đó dùng trình terminal và gõ vào các lệnh sau:
cd C:\RubyDevKit
ruby dk.rb init
ruby dk.rb install

Nếu gặp lỗi liên quan đến ffi (trên Linux), hãy cài gói sau:

sudo apt-get install libffi-dev

Nếu gặp lỗi liên quan đến nokogiri (trên linux), hạy cài gói sau (tham khảo):

sudo apt-get install build-essential patch ruby-dev zlib1g-dev liblzma-dev
gem install nokogiri

6 Đến đây nếu làm tiếp các bước dưới, rất có thể bạn sẽ gặp lỗi Could not find … in any of the sources. Có hai cách xử lý tình huống này.

Bạn dùng xem xem thông báo lỗi (màu đỏ) báo là bạn thiếu file gì, ví dụ Could not find abc-xyz-1.0.0 in any of the sources, thì bạn cài ngay dependency đó bằng dòng lệnh:

gem install abc-xyz

Bạn mở file Gemfile.lock lên (bằng Notepad hoặc Sublime) và sửa các dòng bên dưới dòng PLATFORMS (cuối file) thành (xem thêm):

PLATFORMS
java

7 Xem như mọi sự đã hoàn tất, bây giờ bạn cần một trang Jekyll hoàn chỉnh, bạn có thể download các theme Jekyll ở đây. Bạn cũng có thể chỉ cần tạo một file index.html đơn giản để thử nghiệm, download một file ví dụ tại đây.

Trong trường hợp bạn dùng một theme Jekyll có sẵn, bạn cần chép tất cả các thứ trong thư mục chứa theme đó vào trong thư mục jekyll-local-site-repo-name đã tạo ở trên, nhớ là chừa ra hai file Gemfile và chạy các lệnh như ở các bước trên. Sau đó bạn cần sửa lại file _config.yml ngay chỗ url:

url: "http://localhost:4000"

8 Sau khi các bước chuẩn bị hoàn tất, bạn tiến hành chạy server local

bundle exec jekyll serve
Các lỗi phát sinh (nếu có)

Nếu xuất hiện lỗi Dependency error: Yikes!…jekyll-remote-theme…library “libcurl.dll”…, bạn có thể khắc phục bằng các cách sau

  1. Đầu tiên cần phải đảm bảo bạn đã cài gem jekyll-remote-theme. Cài bằng câu lệnh gem install jekyll-remote-theme, sau đó cần update lại bundle bằng lệnh bundle update.
  2. Bạn cần có thư viện libcurl.dll trong máy mình. Có thể download thư viện đó ở đây (chọn download theo đường dẫn dạng /7.40.0/dist-w64/curl-7.40.0-devel-mingw64.7z). Sau khi download về, giải nén, vào thư mục bin, copy file libcurl.dll và chép vào thư mục cài đặt ruby, ví dụ C:\Ruby24-x64\bin.
  3. Bạn cũng có thể giải nén file chứa libcurl ở trên về ra một thư mục, sau đó thêm đường dẫn đến thư mục này và biến PATH của hệ thống Windows. Đọc thêm tại đây.

Nếu xuất hiện lỗi Invalid argument @ dir_s_mkdir …https, có thể trong file index hay _config.yml của bạn có chứa các đường link https dạng như redirect_from. Chỉ cần tìm và xóa các dòng này đi là được!

9 Mở trình duyệt và gõ vào đường dẫn http://localhost:4000/ hoặc http://127.0.0.1:4000/ để thấy kết quả!

Mỗi khi bạn thay đổi trong thư mục chứa site jekyll local, nó sẽ tự động cập nhật ngay lập tức và có tác dụng khi bạn refresh lại trình duyệt. Trong trường hợp bạn muốn dừng server lại thì nhấn Ctrl + C trong trình terminal và gõ Y hay lần là được.

10 Nếu bạn muốn chạy server local của nhiều trang jekyll cùng lúc thì bạn có thể sử dụng nhiều port khác nhau. “Port” ở các bước trên là 4000. Ở bước 8, bạn thay đổi dòng lệnh tí để có thể chọn port cụ thể cho một trang nào đó như sau:

bundle exec jekyll serve --port 1234

Bạn có thể thay 1234 bởi bất cứ số nào bạn muốn. Sau đó hãy vào trang http://localhost:1234 để truy cập.

Chúc bạn thành công, nếu có xuất hiện những điều trái mong muốn, vui lòng comment bên dưới để trao đổi thêm nhé.