guidebook 0.1.73

HonKit/GitBook compatible static book generator
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# Cấu hình

Cấu hình là tùy chọn. guidebook hoạt động mà không cần cấu hình.

## book.json

Tạo file `book.json` trong thư mục gốc của sách:

```json
{
    "title": "Sách của tôi",
    "plugins": [
        "collapsible-chapters",
        "back-to-top-button",
        "mermaid-md-adoc"
    ],
    "styles": {
        "website": "styles/website.css"
    }
}
```

## Tùy chọn

| Tùy chọn | Mô tả | Mặc định |
|----------|-------|----------|
| `title` | Tiêu đề sách | `"My Book"` |
| `plugins` | Plugin được bật | Xem bên dưới |
| `styles.website` | File CSS tùy chỉnh | `null` |
| `variables` | Biến do người dùng định nghĩa (`{{ book.xxx }}`) | `{}` |
| `hardbreaks` | Coi xuống dòng đơn là `<br>` | `false` |
| `math` | Bật rendering công thức KaTeX | `false` |
| `externalize_svg` | Tách SVG inline thành file riêng | `false` |
| `inline_svg` | Nhúng file SVG vào HTML | `false` |
| `fetchRemoteImages` | Tải hình ảnh remote khi build | `false` |
| `openapi` | File đặc tả OpenAPI/Swagger UI | `null` |

## Plugin mặc định

Các plugin sau được bật mặc định (không cần cấu hình):

- `collapsible-chapters` - Sidebar có thể thu gọn
- `back-to-top-button` - Nút quay lại đầu trang
- `mermaid-md-adoc` - Hỗ trợ biểu đồ Mermaid
- `fontsettings` - Điều chỉnh font và theme (trắng/sepia/tối)

Để tắt plugin mặc định, thêm tiền tố `-`:

```json
{
    "plugins": ["-mermaid-md-adoc"]
}
```

## Biến

Định nghĩa biến tùy chỉnh và sử dụng trong Markdown với cú pháp Nunjucks/Jinja2:

```json
{
    "variables": {
        "version": "1.0.0",
        "appName": "My App"
    }
}
```

Trong Markdown:

```markdown
Phiên bản hiện tại: {{ book.version }}

Chào mừng đến {{ book.appName }}!
```

Biến trong code block (`` ` `` và ` ``` `) không được mở rộng.

## Công thức (KaTeX)

Bật rendering công thức:

```json
{
    "math": true
}
```

Dùng `$...$` cho công thức inline và `$$...$$` cho công thức display.

## Tải hình ảnh remote

Tải hình ảnh HTTPS remote khi build để xem offline:

```json
{
    "fetchRemoteImages": true
}
```

Hình ảnh được cache trong `_remote_images/` với tên file dựa trên CRC32. Kích thước tối đa 50 MB mỗi hình.

## OpenAPI / Swagger UI

Tạo Swagger UI từ đặc tả OpenAPI:

```json
{
    "openapi": "swagger.json"
}
```

Cho nhiều API:

```json
{
    "openapi": {
        "api-docs": "swagger/v1.json",
        "admin-api": "swagger/admin.json"
    }
}
```

## CSS tùy chỉnh

Tạo file CSS và tham chiếu trong `book.json`:

```css
/* styles/website.css */
.book {
    font-family: "Noto Sans", sans-serif;
}

.markdown-section h2 {
    border-left: 4px solid #007acc;
    padding-left: 10px;
}
```