Thư viện khối soạn thảo Docs Coffee: viết bài đồng nhất chuẩn GitBook

1. Quy tắc chung khi soạn bài

• Soạn ở chế độ HTML view của Blogger, không dán từ Word.
• Dùng <h2> cho mục lớn và <h3> cho mục con — theme tự sinh mục lục "Trên trang này" khi bài có từ 2 tiêu đề.
• Mỗi bài mở đầu bằng khối Tóm tắt cốt lõi (callout coffee) để trang chủ và trang nhãn trích đúng ý chính.
• Bảng và khối code tự cuộn ngang trên màn hình hẹp, không cần chỉnh gì thêm.

2. Callout — bốn sắc thái

Bốn class: coffee (tóm tắt), note (thông tin), tip (mẹo), warning (cảnh báo).

<div class="cd-callout tip"><i class="fa-solid fa-check"></i>
  <div><b>Tiêu đề gợi ý</b>Nội dung lời khuyên ngắn gọn, một tới ba câu.</div>
</div>

3. Các bước tuần tự (Steps)

Dùng khi mô tả quy trình có thứ tự bắt buộc. Số thứ tự và đường nối tự vẽ:

1. Chuẩn bịCân 18g bột, lau khô giỏ lọc.
2. Phân bổKhuấy WDT rồi san phẳng bề mặt.
3. Chiết xuấtNén một lần, chiết 36g trong 25–32 giây.

<ol class="cd-steps">
  <li><b>Chuẩn bị</b>Cân 18g bột, lau khô giỏ lọc.</li>
  <li><b>Phân bổ</b>Khuấy WDT rồi san phẳng bề mặt.</li>
  <li><b>Chiết xuất</b>Nén một lần, chiết 36g trong 25–32 giây.</li>
</ol>

4. Mục gấp gọn (Accordion)

Dùng cho FAQ hoặc nội dung phụ không nên chiếm chỗ:

<details class="cd-acc">
  <summary>Câu hỏi thường gặp về độ mịn</summary>
  <div class="cd-acc-body"><p>Nội dung trả lời, có thể chứa đoạn văn, bảng, danh sách.</p></div>
</details>

5. Hình ảnh có chú thích và video

<figure class="cd-fig">
  <img src="URL-ẢNH" alt="Mô tả ảnh"/>
  <figcaption>Chú thích ảnh: nguồn, bối cảnh, điểm cần nhìn.</figcaption>
</figure>

Video YouTube nhúng khung 16:9 tự co giãn:

<div class="cd-video">
  <iframe src="https://www.youtube.com/embed/MÃ-VIDEO" title="Tên video" allowfullscreen></iframe>
</div>

6. Khối code có tiêu đề file

Bột: 15g — Nước: 250g @ 93°C
Bloom 40g / 40 giây, kết thúc 2:45

<div class="cd-codeblock">
  <div class="cd-code-title"><i class="fa-regular fa-file-code"></i> công-thức.txt</div>
  <pre><code>Bột: 15g — Nước: 250g @ 93°C
Bloom 40g / 40 giây, kết thúc 2:45</code></pre>
</div>

7. Checklist

• Đã tráng nóng phễu và bình chứa
• Đã cân bột với sai số dưới 0,2g
• Đã ghi thời gian chiết vào sổ ca

<ul class="cd-check">
  <li>Đã tráng nóng phễu và bình chứa</li>
  <li>Đã cân bột với sai số dưới 0,2g</li>
  <li>Đã ghi thời gian chiết vào sổ ca</li>
</ul>

8. Thẻ liên kết điều hướng

Dùng ở cuối bài để dẫn sang chuyên đề liên quan:

<div class="cd-linkgrid">
  <a class="cd-linkcard" href="/search/label/Kỹ%20thuật%20pha%20chế">
    <b>Kỹ thuật pha chế</b>
    <span>Espresso, pour over, phin và các phương pháp khác.</span>
  </a>
  <a class="cd-linkcard" href="/search/label/Thuật%20ngữ">
    <b>Từ điển thuật ngữ</b>
    <span>Tra cứu khái niệm chuẩn SCA theo bảng chữ cái.</span>
  </a>
</div>

9. Bảng thông số (Spec)

Gọn hơn bảng thường khi chỉ có cặp tên – giá trị:

Dose

18g ± 0,2g

Yield

36g (tỷ lệ 1:2)

Thời gian

25 – 32 giây

<dl class="cd-spec">
  <div><dt>Dose</dt><dd>18g ± 0,2g</dd></div>
  <div><dt>Yield</dt><dd>36g (tỷ lệ 1:2)</dd></div>
  <div><dt>Thời gian</dt><dd>25 – 32 giây</dd></div>
</dl>

10. Trích dẫn và nhãn trong dòng

Cà phê ngon là cà phê được lặp lại được.

<blockquote class="cd-quote">
  Cà phê ngon là cà phê được lặp lại được.
  <footer>— Ghi chú nội bộ đội rang</footer>
</blockquote>

Áp dụng cho Espresso và Pour over.

<p>Áp dụng cho <span class="cd-tag accent">Espresso</span> và <span class="cd-tag">Pour over</span>.</p>

11. Tabs — nhiều phiên bản một nội dung

Dùng khi cùng một chủ đề có nhiều biến thể (công thức nóng/đá, ba loại phễu). Nút đầu mang class is-active, số nút phải bằng số pane:

<div class="cd-tabs">
  <div class="cd-tabbar">
    <button class="is-active">Tab 1</button>
    <button>Tab 2</button>
  </div>
  <div class="cd-tabpanes">
    <div class="cd-pane is-active"><p>Nội dung tab 1.</p></div>
    <div class="cd-pane"><p>Nội dung tab 2.</p></div>
  </div>
</div>

12. Nên / Tránh

<div class="cd-dodont">
  <div class="do"><h4><i class="fa-solid fa-check"></i> Nên</h4>
    <ul><li>Việc nên làm thứ nhất</li><li>Việc nên làm thứ hai</li></ul></div>
  <div class="dont"><h4><i class="fa-solid fa-xmark"></i> Tránh</h4>
    <ul><li>Lỗi cần tránh thứ nhất</li><li>Lỗi cần tránh thứ hai</li></ul></div>
</div>

13. Dòng thời gian

Cho diễn biến theo mốc: nhật ký mẻ rang, lộ trình dự án:

<div class="cd-timeline">
  <div><span class="cd-tl-time">0:00</span><b>Mốc thứ nhất</b><p>Mô tả việc xảy ra.</p></div>
  <div><span class="cd-tl-time">4:30</span><b>Mốc thứ hai</b><p>Mô tả việc xảy ra.</p></div>
</div>

14. Dải số liệu

<div class="cd-stats">
  <div><div class="cd-stat-num">18g</div><div class="cd-stat-label">Dose</div></div>
  <div><div class="cd-stat-num">1:2</div><div class="cd-stat-label">Ratio</div></div>
  <div><div class="cd-stat-num">27s</div><div class="cd-stat-label">Thời gian</div></div>
</div>

15. Hộp thuật ngữ trong dòng

<div class="cd-term-box"><b>Thuật ngữ:</b> giải thích ngắn một khái niệm ngay trong dòng chảy bài viết,
kèm <a href="/search/label/Thuật%20ngữ">liên kết sang từ điển</a> khi cần chi tiết.</div>

16. Biểu đồ (Chart.js)

Khối cd-chart nhúng biểu đồ tương tác: dán div chứa JSON cấu hình Chart.js chuẩn (type + data, thêm options nếu cần). Theme tự nạp thư viện chỉ khi trang có biểu đồ, tự tô màu theo bảng màu theme, tự vẽ lại khi đổi chế độ sáng / tối. Hỗ trợ mọi loại: bar, line, pie, doughnut, radar…

<div class="cd-chart">
  <div class="cd-chart-title"><i class="fa-solid fa-chart-column"></i> Thời gian chiết và cảm nhận vị</div>
  <script type="application/json">
  {
    "type": "bar",
    "data": {
      "labels": ["20s", "23s", "26s", "29s", "32s", "35s"],
      "datasets": [
        {"label": "Chua gắt", "data": [9, 7, 4, 2, 1, 1]},
        {"label": "Ngọt cân bằng", "data": [1, 3, 7, 9, 7, 4]},
        {"label": "Đắng khét", "data": [0, 1, 2, 3, 6, 9]}
      ]
    }
  }
  </script>
  <div class="cd-chart-note">Dữ liệu minh hoạ cảm quan theo thời gian chiết, dose 18g — yield 36g.</div>
</div>

Thêm class tall cho biểu đồ cần khung cao hơn (420px thay vì 300px):

<div class="cd-chart tall">
  <div class="cd-chart-title"><i class="fa-solid fa-chart-line"></i> Đường cong nhiệt mẻ rang</div>
  <script type="application/json">
  {
    "type": "line",
    "data": {
      "labels": ["0:00", "1:00", "2:00", "3:00", "4:00", "5:00", "6:00", "7:00", "8:00", "9:00", "10:00"],
      "datasets": [
        {"label": "Nhiệt hạt (°C)", "data": [200, 96, 108, 125, 143, 158, 170, 181, 192, 200, 206]},
        {"label": "RoR (°C/phút)", "data": [null, 14, 13.5, 13, 12, 11, 10.5, 10, 9, 7.5, 5.5]}
      ]
    }
  }
  </script>
</div>

17. Sơ đồ quy trình (Mermaid)

Khối cd-flow vẽ flowchart, sơ đồ quyết định, sơ đồ tuần tự bằng cú pháp Mermaid: viết mã nguồn trong <pre class="cd-flow-src">, theme tự nạp thư viện khi trang có sơ đồ và tô màu theo bảng màu sáng / tối. flowchart TD là từ trên xuống, LR là trái sang phải.

flowchart TD
A[Nếm shot thử] --> B{Vị thế nào?}
B -->|Chua gắt| C[Xay mịn hơn]
B -->|Đắng khét| D[Xay thô hơn]
B -->|Cân bằng| E[Khoá thông số]
C --> A
D --> A

<div class="cd-flow">
  <div class="cd-chart-title"><i class="fa-solid fa-diagram-project"></i> Chỉnh shot theo vị</div>
  <pre class="cd-flow-src">flowchart TD
A[Nếm shot thử] --> B{Vị thế nào?}
B -->|Chua gắt| C[Xay mịn hơn]
B -->|Đắng khét| D[Xay thô hơn]
B -->|Cân bằng| E[Khoá thông số]
C --> A
D --> A</pre>
</div>