Trình diễn tổng hợp

§1.1Dấu nhấn trong dòng

Phép phân tích nhấn mạnh thân thiện với CJK: chữ đậm vẫn đóng được ngay sát dấu câu toàn khổ — **报文。**同时 render thành 报文。同时 chứ không phải mấy dấu sao trơ ra. Nghiêng, gạch ngang và mã trong dòng hoạt động như thường; bật công tắc gemoji thì shortcode kiểu :sparkles: render thành ✨. Ký tự nằm trong mã trong dòng không tham gia bất kỳ phép phân tích nào, nên cặp backtick là cách an toàn để trưng cú pháp: **, $…$ và > [!note] đều hiện nguyên văn. Muốn hiện một dấu sao giữa câu văn, hãy thoát nó — *như thế này* thì giữ nguyên.

§1.2Wikilink

Bật công tắc wikilinks, liên kết [[hai-ngoặc-vuông]] phân giải trên tập ghi chú đúng theo lối wiki: theo id (design-tokens — đi từ trang tiếng Việt, liên kết ưu tiên rơi vào bản dịch cùng ngôn ngữ, thiếu bản dịch mới rơi về bản gốc tiếng Anh), theo bí danh (boundaries dẫn đến ghi chú có id three-way-split), và kèm nhãn đọc được (bài hướng dẫn bắt đầu sử dụng). Đích không phân giải được sẽ render thành liên kết chết có đánh dấu thay vì đánh hỏng bản build — CLI check-wikilinks của engine sẽ báo nó trong CI, nơi chuyện liên kết mục nát thuộc về.

§1.3Bảng: rộng thì cuộn, hẹp thì thành thẻ

Bảng từ sáu cột trở lên nên tự xếp lại mỗi hàng thành một thẻ trong khung hẹp, thay vì ép mỗi ô còn hai ký tự. Bảng bảy cột dưới đây vừa là bảng tra nhanh các biến thể callout, vừa là phép thử sống của chính cơ chế xếp thẻ ấy (thu cửa sổ về cỡ điện thoại mà xem):

Tiêu đề mặc định là tiếng Anh; site thay cả bộ qua tùy chọn calloutLabels của siteMarkdown, ví dụ calloutLabels: { tip: 'Trực giác · Intuition' }. Tiêu đề viết ngay trong cú pháp trích dẫn (> [!tip] Tiêu đề của tôi) luôn thắng.

§2.1Callout: ba cách viết

Thứ nhất, cú pháp trích dẫn kiểu Obsidian/GitHub (có khi bật callouts: true, chạy được cả trong tệp Markdown thuần):

Dấu gấp của Obsidian được tôn trọng — > [!note]- render ở trạng thái gấp, > [!note]+ ở trạng thái mở:

Thứ hai, thành phần của gói trong MDX (astro-inkstone/components/Callout.astro, import theo đường dẫn). Không truyền title thì nó hiện nhãn mặc định của biến thể, đúng nhãn mà cú pháp trích dẫn dùng:

Thứ ba, HTML thô, cả sáu biến thể trong một lượt (khớp một-một với các rule .callout trong base.css):

§2.2Toán

Công thức trong dòng nằm lẫn vào câu chữ: độ sâu quang học đọc là $\tau = \int \kappa \rho \, \mathrm{d}s$. Công thức tách dòng dùng dạng ba dòng ($$ đứng riêng mỗi dòng) — lớp kiểm soát từ chối dạng một dòng, thứ sẽ lặng lẽ render thành công thức nhỏ trong dòng:

Nền công thức cố ý là một tờ giấy khác với nền thân bài, và đổi bộ theo giao diện. Tiện thể, giá tiền đô trong câu văn nhớ thoát ký hiệu: ly cà phê này giá $3.

§3.1Khung mã

Fence có title="…" được thanh tiêu đề mang tên tệp; nút sao chép ở góc là thống nhất toàn site. Chú thích dòng [!code ++] / [!code --] render thành nền diff:

def build_pipeline(opts):
    plugins = [remark_math]  
    plugins = [remark_gemoji, remark_math]  
    return assemble(plugins, guard=opts.guard)

Khung đánh dấu collapse khởi đầu ở trạng thái gấp, mở ra mới chiếm chỗ — hợp với tệp cấu hình dài:

site:
  markdown:
    numbering: chapters
    math: true
    codeFrame: true
    mermaid: true
    callouts: true
    wikilinks: true
  styles:
    - astro-inkstone/styles/tokens.css
    - astro-inkstone/styles/base.css

Tô sáng hai giao diện là nhờ shiki xuất cả hai bộ màu trong một lần; base.css chọn một bộ theo data-theme tại đúng một chỗ — không có màn giằng co độ ưu tiên nào.

§3.2Sơ đồ mermaid

Fence ```mermaid lúc build chỉ để lại chỗ giữ; trình render chỉ được nạp động trên trang có sơ đồ (trang không có thì không trả một xu nào), và tự render lại khi giao diện lật:

flowchart LR
  A["astro-inkbrush<br/>engine: biên tập / phương ngữ / kiểm soát"] --> C["site của bạn<br/>bản sắc / định tuyến / triển khai"]
  B["astro-inkstone<br/>giấy: token / style / pipeline"] --> C
  A -. chung một phương ngữ .-> B

§3.3Các món kèm theo GFM

Danh sách việc và cước chú đi cùng chuyến với GFM:

• tokens đã import
• base.css đã import
• bảng màu bản sắc đã ghi đè

Nhận định nào đáng dẫn nguồn thì gắn cước chú.¹

§4.1Lớp kiểm soát chặn gì trên trang này

Trang này build qua được, tự nó đã chứng minh mọi thứ phía trên đều hợp lệ. Những cách viết sau sẽ đánh hỏng bản build ngay tại chỗ (muốn tận mắt thấy, thử một cái rồi chạy npm run build):

• dấu nhấn mạnh không ghép được cặp, kiểu một ** bỏ ngỏ ở cuối dòng;
• $$x$$ viết trên một dòng (phải dùng dạng ba dòng);
• đề mục đánh số tay — viết tiêu đề của mục này thành ## 9. Lớp kiểm soát… sẽ va vào bộ đánh số lúc build và bị gắn cờ;
• MDX đem ngoặc nhọn trong câu văn ra tính: {0,1,2,3} sẽ chỉ còn render ra mỗi 3, nên lớp kiểm soát đòi dạng thoát {0,1,2,3};
• công thức KaTeX không render nổi (lớp kiểm soát render lại từng công thức ở chế độ nghiêm ngặt, thay vì để chữ đỏ báo lỗi lọt lên trang).