|
| 1 | +# 📝 Jekyll博客写作完全指南 |
| 2 | + |
| 3 | +## 📖 文章结构 |
| 4 | + |
| 5 | +每篇Jekyll博客文章都包含两部分: |
| 6 | +1. **Front Matter**(文件头部的YAML配置) |
| 7 | +2. **正文内容**(Markdown格式) |
| 8 | + |
| 9 | +## 🎯 Front Matter 详解 |
| 10 | + |
| 11 | +每篇文章开头必须有Front Matter,用三个短横线包围: |
| 12 | + |
| 13 | +```yaml |
| 14 | +--- |
| 15 | +layout: post # 布局模板(固定为post) |
| 16 | +title: "文章标题" # 文章标题 |
| 17 | +subtitle: "副标题" # 副标题(可选) |
| 18 | +date: 2025-06-26 10:00:00 # 发布日期和时间 |
| 19 | +author: "Jason" # 作者名 |
| 20 | +header-img: "img/post-bg-example.jpg" # 头部背景图 |
| 21 | +catalog: true # 是否显示目录 |
| 22 | +tags: # 标签 |
| 23 | + - 技术 |
| 24 | + - 学习 |
| 25 | + - 编程 |
| 26 | +--- |
| 27 | +``` |
| 28 | + |
| 29 | +### Front Matter 字段说明 |
| 30 | + |
| 31 | +| 字段 | 必填 | 说明 | |
| 32 | +|------|------|------| |
| 33 | +| `layout` | ✅ | 固定为 `post` | |
| 34 | +| `title` | ✅ | 文章标题 | |
| 35 | +| `subtitle` | ❌ | 副标题,会显示在标题下方 | |
| 36 | +| `date` | ✅ | 发布日期时间,格式:`YYYY-MM-DD HH:MM:SS` | |
| 37 | +| `author` | ✅ | 作者名称 | |
| 38 | +| `header-img` | ❌ | 背景图片路径(相对于网站根目录) | |
| 39 | +| `catalog` | ❌ | 是否显示文章目录,默认false | |
| 40 | +| `tags` | ❌ | 文章标签,可以有多个 | |
| 41 | + |
| 42 | +## 📂 文件命名规则 |
| 43 | + |
| 44 | +文章文件必须放在 `_posts` 文件夹中,文件名格式: |
| 45 | +``` |
| 46 | +YYYY-MM-DD-title.markdown |
| 47 | +``` |
| 48 | + |
| 49 | +**示例:** |
| 50 | +- `2025-06-26-my-first-post.markdown` |
| 51 | +- `2025-06-26-learning-javascript.md` |
| 52 | +- `2025-06-26-技术分享.markdown` |
| 53 | + |
| 54 | +## ✨ Markdown 语法 |
| 55 | + |
| 56 | +### 标题 |
| 57 | +```markdown |
| 58 | +# 一级标题 |
| 59 | +## 二级标题 |
| 60 | +### 三级标题 |
| 61 | +#### 四级标题 |
| 62 | +``` |
| 63 | + |
| 64 | +### 段落和换行 |
| 65 | +```markdown |
| 66 | +这是第一段内容。 |
| 67 | + |
| 68 | +这是第二段内容。 |
| 69 | + |
| 70 | +段落内换行,在行末加两个空格 |
| 71 | +然后这里就是新的一行。 |
| 72 | +``` |
| 73 | + |
| 74 | +### 强调 |
| 75 | +```markdown |
| 76 | +**粗体文字** |
| 77 | +*斜体文字* |
| 78 | +***粗体加斜体*** |
| 79 | +~~删除线~~ |
| 80 | +``` |
| 81 | + |
| 82 | +### 列表 |
| 83 | +```markdown |
| 84 | +## 无序列表 |
| 85 | +- 第一项 |
| 86 | +- 第二项 |
| 87 | + - 子项目 |
| 88 | + - 另一个子项目 |
| 89 | +- 第三项 |
| 90 | + |
| 91 | +## 有序列表 |
| 92 | +1. 第一步 |
| 93 | +2. 第二步 |
| 94 | +3. 第三步 |
| 95 | +``` |
| 96 | + |
| 97 | +### 链接 |
| 98 | +```markdown |
| 99 | +[链接文字](https://example.com) |
| 100 | +[链接文字](https://example.com "鼠标悬停显示的标题") |
| 101 | +``` |
| 102 | + |
| 103 | +### 图片 |
| 104 | +```markdown |
| 105 | + |
| 106 | + |
| 107 | +``` |
| 108 | + |
| 109 | +### 代码 |
| 110 | +````markdown |
| 111 | +## 行内代码 |
| 112 | +这是一段包含 `代码` 的文字。 |
| 113 | + |
| 114 | +## 代码块 |
| 115 | +```javascript |
| 116 | +function hello() { |
| 117 | + console.log("Hello World!"); |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +```python |
| 122 | +def hello(): |
| 123 | + print("Hello World!") |
| 124 | +``` |
| 125 | +```` |
| 126 | + |
| 127 | +### 引用 |
| 128 | +```markdown |
| 129 | +> 这是一段引用文字 |
| 130 | +> 可以有多行 |
| 131 | +>> 还可以嵌套引用 |
| 132 | +``` |
| 133 | + |
| 134 | +### 表格 |
| 135 | +```markdown |
| 136 | +| 列1 | 列2 | 列3 | |
| 137 | +|-----|-----|-----| |
| 138 | +| 数据1 | 数据2 | 数据3 | |
| 139 | +| 数据4 | 数据5 | 数据6 | |
| 140 | +``` |
| 141 | + |
| 142 | +## 🎨 特殊功能 |
| 143 | + |
| 144 | +### 目录功能 |
| 145 | +在Front Matter中设置 `catalog: true`,会自动为文章生成目录。 |
| 146 | + |
| 147 | +### 数学公式(如果启用MathJax) |
| 148 | +```markdown |
| 149 | +行内公式:$E = mc^2$ |
| 150 | + |
| 151 | +块级公式: |
| 152 | +$$ |
| 153 | +\frac{n!}{k!(n-k)!} = \binom{n}{k} |
| 154 | +$$ |
| 155 | +``` |
| 156 | + |
| 157 | +### 代码高亮 |
| 158 | +支持多种编程语言的语法高亮: |
| 159 | +- `javascript`, `js` |
| 160 | +- `python`, `py` |
| 161 | +- `java` |
| 162 | +- `html` |
| 163 | +- `css` |
| 164 | +- `bash`, `shell` |
| 165 | +- `json` |
| 166 | +- `xml` |
| 167 | +- 等等... |
| 168 | + |
| 169 | +## 📝 文章模板 |
| 170 | + |
| 171 | +### 技术文章模板 |
| 172 | +```markdown |
| 173 | +--- |
| 174 | +layout: post |
| 175 | +title: "技术文章标题" |
| 176 | +subtitle: "简短的副标题描述" |
| 177 | +date: 2025-06-26 10:00:00 |
| 178 | +author: "Jason" |
| 179 | +header-img: "img/post-bg-tech.jpg" |
| 180 | +catalog: true |
| 181 | +tags: |
| 182 | + - 技术 |
| 183 | + - 编程 |
| 184 | + - 教程 |
| 185 | +--- |
| 186 | + |
| 187 | +## 前言 |
| 188 | + |
| 189 | +简单介绍文章的背景和目的。 |
| 190 | + |
| 191 | +## 问题描述 |
| 192 | + |
| 193 | +详细描述要解决的问题。 |
| 194 | + |
| 195 | +## 解决方案 |
| 196 | + |
| 197 | +### 方法一 |
| 198 | + |
| 199 | +具体的解决步骤... |
| 200 | + |
| 201 | +### 方法二 |
| 202 | + |
| 203 | +另一种解决方案... |
| 204 | + |
| 205 | +## 代码示例 |
| 206 | + |
| 207 | +```javascript |
| 208 | +// 示例代码 |
| 209 | +function example() { |
| 210 | + return "Hello World!"; |
| 211 | +} |
| 212 | +``` |
| 213 | + |
| 214 | +## 总结 |
| 215 | + |
| 216 | +总结文章的要点和收获。 |
| 217 | + |
| 218 | +## 参考资料 |
| 219 | + |
| 220 | +- [参考链接1](https://example.com) |
| 221 | +- [参考链接2](https://example.com) |
| 222 | +``` |
| 223 | + |
| 224 | +### 生活感悟模板 |
| 225 | +```markdown |
| 226 | +--- |
| 227 | +layout: post |
| 228 | +title: "感悟文章标题" |
| 229 | +subtitle: "生活中的小思考" |
| 230 | +date: 2025-06-26 20:00:00 |
| 231 | +author: "Jason" |
| 232 | +header-img: "img/post-bg-life.jpg" |
| 233 | +catalog: false |
| 234 | +tags: |
| 235 | + - 生活 |
| 236 | + - 感悟 |
| 237 | + - 思考 |
| 238 | +--- |
| 239 | + |
| 240 | +## 起因 |
| 241 | + |
| 242 | +描述触发这次思考的事件... |
| 243 | + |
| 244 | +## 思考过程 |
| 245 | + |
| 246 | +详细描述自己的思考过程... |
| 247 | + |
| 248 | +## 感悟 |
| 249 | + |
| 250 | +总结自己的心得体会... |
| 251 | + |
| 252 | +## 后记 |
| 253 | + |
| 254 | +一些延伸的思考或计划... |
| 255 | +``` |
| 256 | + |
| 257 | +## 🚀 发布流程 |
| 258 | + |
| 259 | +1. **创建文章文件** |
| 260 | + ```bash |
| 261 | + # 在 _posts 文件夹中创建新文件 |
| 262 | + 2025-06-26-my-new-post.markdown |
| 263 | + ``` |
| 264 | + |
| 265 | +2. **编写内容** |
| 266 | + - 添加Front Matter |
| 267 | + - 用Markdown编写正文 |
| 268 | + |
| 269 | +3. **本地预览**(可选) |
| 270 | + ```bash |
| 271 | + bundle exec jekyll serve |
| 272 | + ``` |
| 273 | + |
| 274 | +4. **提交到GitHub** |
| 275 | + ```bash |
| 276 | + git add . |
| 277 | + git commit -m "发布新文章:文章标题" |
| 278 | + git push origin master |
| 279 | + ``` |
| 280 | + |
| 281 | +5. **等待部署** |
| 282 | + - GitHub Pages会自动构建 |
| 283 | + - 通常2-5分钟后文章就会在线显示 |
| 284 | + |
| 285 | +## 💡 写作技巧 |
| 286 | + |
| 287 | +### 1. 标题要吸引人 |
| 288 | +- ✅ "5分钟学会JavaScript闭包" |
| 289 | +- ❌ "关于JavaScript的一些知识" |
| 290 | + |
| 291 | +### 2. 使用合适的标签 |
| 292 | +- 技术文章:技术栈名称、编程语言 |
| 293 | +- 生活文章:生活、感悟、思考 |
| 294 | +- 学习笔记:学习、笔记、总结 |
| 295 | + |
| 296 | +### 3. 添加目录 |
| 297 | +对于长文章,建议开启 `catalog: true` |
| 298 | + |
| 299 | +### 4. 图片使用 |
| 300 | +- 将图片放在 `img/` 文件夹中 |
| 301 | +- 使用相对路径引用:`img/your-image.jpg` |
| 302 | + |
| 303 | +### 5. 代码格式化 |
| 304 | +- 使用合适的语言标识符 |
| 305 | +- 添加注释说明关键部分 |
| 306 | + |
| 307 | +## 🎯 SEO优化 |
| 308 | + |
| 309 | +1. **标题优化**:包含关键词,简洁明了 |
| 310 | +2. **标签使用**:选择相关性强的标签 |
| 311 | +3. **内容质量**:原创、有价值的内容 |
| 312 | +4. **图片优化**:添加alt属性描述 |
| 313 | + |
| 314 | +--- |
| 315 | + |
| 316 | +现在你已经掌握了Jekyll博客的写作方法!开始创作你的第一篇技术文章吧! 🎉 |
0 commit comments