Chủ đề Skinny Bones là một bộ khung khởi tạo Jekyll tối giản, được thiết kế để xây dựng nhanh các trang web tĩnh hoặc blog cá nhân với khả năng tùy chỉnh cao. Dưới đây là danh sách các vấn đề thường gặp cùng giải pháp thực tế — được viết lại rõ ràng, không trùng lặp và cập nhật theo cấu trúc hiện đại của dự án.

Cài đặt và môi trường phát triển

Vấn đề 1: Lỗi khi chạy bundle install
Đảm bảo Ruby (≥ 3.0) và Bundler đã được cài đặt. Thay vì sao chép toàn bộ kho lưu trữ, hãy khởi tạo dự án bằng cách sử dụng gem theme:

gem install jekyll-theme-skinny-bones
jekyll new my-site --force --theme jekyll-theme-skinny-bones
cd my-site
bundle exec jekyll serve

Nếu gặp lỗi thiếu Bundler, chạy gem install bundler --user-install và thêm đường dẫn gem vào $PATH.

Vấn đề 2: Cảnh báo Liquid như undefined variable 'site.owner'
Nguyên nhân thường do thiếu cấu hình trong _config.yml. Đảm bảo khối owner tồn tại và đúng định dạng YAML:

owner:
  name: "Nguyễn Văn A"
  email: "contact@example.com"
  avatar: "/assets/images/avatar.png"

Lưu ý: Không dùng dấu gạch ngang (-) trước owner, và tránh khoảng trắng thừa sau dấu hai chấm.

Tùy chỉnh giao diện

Vấn đề 3: Thay đổi màu sắc và phông chữ không có hiệu lực
Các biến Sass nằm trong _sass/abstracts/_variables.scss. Cập nhật giá trị như sau:

$color-primary: #3b5998;
$color-accent: #f7941e;
$font-stack-base: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;

Sau đó, đảm bảo file assets/css/main.scss nhập đúng đường dẫn:

@import "abstracts/variables";

Vấn đề 4: Mục điều hướng không xuất hiện hoặc dẫn sai liên kết
Tệp cấu hình menu nằm ở _data/nav.yml. Định dạng hợp lệ phải là mảng các đối tượng:

- label: Trang chủ
  href: "/"
- label: Giới thiệu
  href: "/gioi-thieu/"
- label: Bài viết
  href: "/bai-viet/"

Để áp dụng thay đổi, chạy bundle exec jekyll build --incremental hoặc xóa thư mục .jekyll-cache trước khi khởi động lại máy chủ.

Quản lý nội dung

Vấn đề 5: Bài viết không hiển thị trên trang danh sách
Kiểm tra phần front matter của tệp Markdown — bắt buộc phải có layout: post và ngày hợp lệ:

---
layout: post
title: "Hướng dẫn Jekyll cơ bản"
date: 2024-05-12
author: "Nguyễn Văn A"
categories: [lập-trình, jekyll]
---

Đảm bảo tên thư mục chứa bài viết là _posts (không viết sai thành _post hay posts).

Vấn đề 6: Ảnh đại diện tác giả không hiển thị
Đặt ảnh vào thư mục assets/images/ và cập nhật đường dẫn tuyệt đối trong _config.yml:

owner:
  avatar: "/assets/images/me.jpg"

Kích thước khuyến nghị: 200×200 px, định dạng WebP hoặc AVIF để tối ưu tải trang.

Mở rộng chức năng

Vấn đề 7: Bình luận Disqus không hoạt động
Thêm cấu hình vào _config.yml dưới dạng top-level key (không lồng trong owner):

disqus:
  shortname: "ten-ngan-cua-ban"

Trong layout _layouts/post.html, chèn đoạn mã sau tại vị trí mong muốn:

{% if site.disqus.shortname %}{% include disqus-comments.html %}{% endif %}

Vấn đề 8: Tốc độ tải trang chậm trên thiết bị di động
Áp dụng ba cải tiến không cần plugin:

• Dùng image_tag Liquid tag để tự động sinh srcset cho ảnh: {% image /assets/images/photo.jpg alt="Mô tả" %}
• Loại bỏ các tập tin không cần thiết khỏi quá trình build bằng exclude: trong _config.yml, ví dụ: ["node_modules/", "Gruntfile.js"]
• Tối ưu CSS bằng jekyll-minifier: thêm gem vào Gemfile và kích hoạt trong _config.yml với plugins: [jekyll-minifier]

Thiết kế phản hồi và tích hợp

Vấn đề 9: Giao diện bị lệch trên màn hình nhỏ
Kiểm tra lớp CSS .page-content trong _sass/components/_page.scss. Điều chỉnh padding và width cho các breakpoint:

@media (max-width: 600px) {
  .page-content {
    margin-inline: 1rem;
  }
}

Vấn đề 10: Thêm nút chia sẻ mạng xã hội
Tạo file mới _includes/social-share.html với nội dung:

<div class="social-share">
  <a href="https://www.facebook.com/sharer/sharer.php?u={{ page.url | absolute_url }}" target="_blank" rel="noopener">Facebook</a>
  <a href="https://twitter.com/intent/tweet?url={{ page.url | absolute_url }}&text={{ page.title | escape }}" target="_blank" rel="noopener">Twitter</a>
</div>

Sau đó chèn vào layout bài viết bằng {% include social-share.html %}.