menu

Làm sao build local Jekyll site?

Đăng lúc 16/11/2017, trong chuyên mục Liquid và Jekyll

Nếu như bạn sử dụng Github Pages và Jekyll để tạo trang web như trang Tôi Tự Học, 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ó.

Tóm tắt các lệnh sử dụng

Dành cho những ai đã cài đặt thành công các gói/phần mềm cần thiết và sử dụng các câu lệnh sau cho những lần sử dụng tiếp theo.

Tạo trang mới

  • Tạo repo chứa trang mới: git init <tên-repo>
  • Chuyển đến thư mục chứa repo: cd <tên-repo>
  • Tạo nhánh gh-pages (nếu muốn): git checkout -b gh-pages
  • Tạo file Gemfile với nội dung
    source 'https://rubygems.org'
    gem 'github-pages', group: :jekyll_plugins
    
  • Install các gems cần thiết: bundle install (nếu gặp lỗi phát sinh, vui lòng đọc trong bài viết)
  • Sửa lại file Gemfile.lock chỗ PLATFORMS với nội dung java.
  • Sửa file _config.yml: url: "http://localhost:4000"
  • Chạy server local: bundle exec jekyll serve
  • Chạy nhiều server cùng lúc, mỗi server một port: bundle exec jekyll serve --port số-bạn-chọn
  • Mở trang web: vào http://localhost:4000

Sử dụng trang đã có

  • Đi đến repo chứa trang web: cd <tên-repo>
  • Chạy server: bundle exec jekyll serve (nếu gặp lỗi phát sinh, vui lòng đọc trong bài viết)
  • Chạy nhiều server cùng lúc, mỗi server một port: bundle exec jekyll serve --port số-bạn-chọn
  • Có chỉnh sửa và thêm vào nhánh hiện hành: git add * và commit git commit -m "ghi chú" (cũng có thể không cần làm bước này)
  • Mở trang web: vào http://localhost:4000
  • Tắt server bằng cách nhấn Ctrl+C và nhấn tiếp Y hai lần để xác nhậ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.

Đầ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.

  1. Với Windows, bạn download và cài Git từ đây.
  2. Với Linux (Debian/Ubuntu), bạn dùng câu lệnh sau
    sudo apt-get install git-all
    
  3. 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.

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

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

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

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 đó bạn 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.

  • face 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
    

Đế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.

  1. 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
    
  2. 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
    

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"

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
  • face 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!

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.

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é.

Tham khảo thêm

[1] Setting up your GitHub Pages site locally with Jekyll
[2] Cài đặt Git trên các nền tảng.

jekyll
git
tạo website
Top