什么是Markdown?(必看)#

为什么要使用Markdown?#

使用传统的编辑方案，你得像个鼠标杂技演员，一会儿点粗体一会儿调字号，忙活半天像给文字铺地砖——累到想把键盘当枕头。但Markdown不一样，这货堪称”文字界的懒人福音”，就像发现外卖软件的厨房小白，从此告别格式挣扎，专注干饭…啊不，专注写作。

有人说这玩意叫”马可蛋”，因为学会它，你敲字的速度能赶上马在奔跑中下蛋的概率——听着离谱，但用过的人都知道：这概率居然挺高！

这货到底是个啥？#

简单说，Markdown是一种让文字”自己打扮自己”的神奇咒语。2004年有个叫约翰·格鲁伯的老哥大概是受够了HTML的啰嗦，大手一挥发明了这东西——就像嫌系鞋带麻烦直接发明魔术贴一样天才。

它的脾气特别好：

• 用#号当帽子，文字就知道自己是标题；
• 给句子套个*号，它就乖乖斜着站；
• 想列清单？加个短横线，文字立马排好队站军姿。

最绝的是，就算你忘了给它”施法”，纯文本状态下的Markdown也长得眉清目秀，不像某些格式文件，换个软件打开就变成乱码抽象画。

凭啥它比Word香？#

Word就像个堆满按钮的战斗机驾驶舱，想加粗文字得先找半天按钮；Markdown则是共享单车，扫码就走。

• 省脑子：记住几个符号比背Office快捷键容易，就像记外卖电话比背菜谱简单；
• 不挑设备：在手机上敲的.md文件，到电脑上打开照样整整齐齐，不像某些文档换个设备就”水土不服”；
• 变身达人：想变HTML？变PDF？变Word？它都行，堪比文字界的变形金刚；
• 适合装X：程序员看你用Markdown写文档会说”哥们儿懂行”，用Word则可能被吐槽”还在用记事本呢？“

哪些人该学这招？#

• 写技术文档的码农：再也不用在代码里插一堆<b>标签，就像给汉堡包插牙签——多此一举；
• 记笔记的学生党：上课记重点时，用##标标题比画下划线快10倍，期末复习时再也不用对着乱涂的笔记本发呆；
• 发博客的博主：在知乎、简书敲文时，**加粗比找工具栏按钮爽，就像用语音输入代替手写；
• 摸鱼爱好者：格式搞定快，摸鱼时间多，懂的都懂。

Markdown学习资源#

📚 推荐学习地址：菜鸟教程 - Markdown教程 （偷偷说：这教程简单到猫都能学会，前提是猫想学）

最后友情提示：学会Markdown不能让马真下蛋，但能让你从格式奴隶变成文字甩手掌柜。现在就打开记事本试试——# 我要当效率大师，怎么样，是不是有内味儿了？

单文件方案#

这是在Mizuka博客系统中创建文章的两种方法之一。这种方法适用于简单的文章，不需要管理大量图片资源的情况。 单文件方案会导致RSS无法正常构建图片的路径(指本地,如果你使用图床那么不会有这个问题),如果你需要使用rss功能请使用文件夹写作方案

创建文章#

1. 在src/content/posts目录下创建一个新的Markdown文件，文件名应该具有描述性，例如my-first-post.md。
2. 在文件中添加frontmatter（前置元数据），这是文章的配置信息，必须包含title和description字段：

1
---
2
title: Markdown Tutorial
3
published: 2025-01-20
4
pinned: true
5
description: A simple example of a Markdown blog post.
6
tags: [Markdown, Blogging]
7
category: Examples
8
licenseName: "Unlicensed"
9
author: emn178
10
sourceLink: "https://github.com/emn178/markdown"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: 'https://example.com/image.jpg'
15
  alt: '图片描述'
16
pubDate: 2025-01-20
17
---

Frontmatter字段详解#

frontmatter支持的字段包括：

Markdown学习资源#

如果您还不熟悉Markdown语法，建议先学习基础知识：

📚 推荐学习地址：菜鸟教程 - Markdown教程

这个教程涵盖了：

• Markdown基本语法
• 标题、段落、换行
• 字体样式（粗体、斜体等）
• 列表、链接、图片
• 代码块、表格
• 高级功能

掌握这些基础语法后，您就可以轻松编写美观的博客文章了！

Frontmatter最佳实践#

1
published: 2025-01-20
2
date: 2025-01-20
3
pubDate: 2025-01-20

1
tags: [Vue.js, JavaScript, Frontend, Tutorial]
2
category: Web Development

1
---
2
title: "Vue.js 3 组合式API完全指南"
3
published: 2025-01-20
4
pinned: false
5
description: "深入了解Vue.js 3的组合式API，包括setup函数、响应式系统和生命周期钩子。"
6
tags: [Vue.js, JavaScript, Frontend, API]
7
category: "Web Development"
8
licenseName: "CC BY 4.0"
9
author: "张三"
10
sourceLink: "https://github.com/zhangsan/vue3-guide"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: 'https://example.com/vue3-cover.jpg'
15
  alt: 'Vue.js 3 组合式API指南封面'
16
pubDate: 2025-01-20
17
---
18

19
# Vue.js 3 组合式API完全指南
20

21
在这篇文章中，我们将深入探讨Vue.js 3的组合式API...

预览文章#

保存文件后，可以在浏览器中预览文章。将文章文件名（不包括.md扩展名）拼接到预览URL的末尾即可查看。 例如，如果本地开发服务器运行在http://localhost:4321/，文章文件名为my-first-post.md，则可以通过http://localhost:4321/posts/my-first-post访问文章。

如果文章尚未创建或文件名错误，页面将显示404错误。当你预览一个尚未创建的文章时，控制台会显示不同的输出，这有助于进行故障排查。

链接到文章#

要在博客页面或其他页面中链接到你的文章，可以使用标准的HTML <a> 标签：

1
<a href="/posts/my-first-post/">我的第一篇文章</a>

确保链接的href属性指向正确的文章路径。

添加图片#

如果需要在文章中添加图片，可以将图片文件放在public目录下，然后在文章中通过相对路径引用：

1
![图片描述](/images/my-image.png)

创建多篇文章#

你可以在src/content/posts/目录下创建多个Markdown文件，每个文件代表一篇文章。例如：

1
src/content/posts/
2
├── my-first-post.md
3
├── my-second-post.md
4
└── my-third-post.md

每篇文章都是一个独立的Markdown文件，文件名将被用作文章的URL路径。

链接多篇文章#

要在博客页面中链接到多篇文章，可以创建一个文章列表：

1
<ul>
2
  <li><a href="/posts/my-first-post/">我的第一篇文章</a></li>
3
  <li><a href="/posts/my-second-post/">我的第二篇文章</a></li>
4
  <li><a href="/posts/my-third-post/">我的第三篇文章</a></li>
5
</ul>

确保每个链接都指向正确的文章路径。

注意事项#

• 文件名将被用作文章的URL路径，所以应该具有描述性且不含特殊字符
• frontmatter中的date字段是可选的，如果不提供，系统会使用文件的创建日期
• 这种方法适合简单的文章，但如果文章包含大量图片，建议使用子文件夹方案

文件夹方案（推荐）#

这是在Mizuka博客系统中创建文章的推荐方法。这种方法更适合复杂的文章，特别是包含大量图片或其他资源的文章。

创建文章#

1. 在src/content/posts目录下创建一个新的文件夹，文件夹名应该具有描述性，例如my-complex-post。
2. 在新创建的文件夹中创建一个名为index.md的文件。
3. 在index.md文件中添加frontmatter（前置元数据），这是文章的配置信息，必须包含title和description字段：

1
---
2
title: Markdown Tutorial
3
published: 2025-01-20
4
pinned: true
5
description: A simple example of a Markdown blog post.
6
tags: [Markdown, Blogging]
7
category: Examples
8
licenseName: "Unlicensed"
9
author: emn178
10
sourceLink: "https://github.com/emn178/markdown"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: './cover.jpg'
15
  alt: '文章封面'
16
pubDate: 2025-01-20
17
---

Frontmatter字段详解#

frontmatter支持的字段包括：

Markdown学习资源#

如果您还不熟悉Markdown语法，建议先学习基础知识：

📚 推荐学习地址：菜鸟教程 - Markdown教程

这个教程涵盖了：

• Markdown基本语法
• 标题、段落、换行
• 字体样式（粗体、斜体等）
• 列表、链接、图片
• 代码块、表格
• 高级功能

掌握这些基础语法后，您就可以轻松编写美观的博客文章了！

Frontmatter最佳实践#

1
published: 2025-01-20
2
date: 2025-01-20
3
pubDate: 2025-01-20

1
tags: [Vue.js, JavaScript, Frontend, Tutorial]
2
category: Web Development

1
image:
2
  url: './cover.jpg'  # 相对于当前文件夹
3
  alt: '文章封面图片描述'

1
---
2
title: "React Hooks深度解析"
3
published: 2025-01-20
4
pinned: true
5
description: "全面解析React Hooks的使用方法和最佳实践，包含大量代码示例和图片说明。"
6
tags: [React, JavaScript, Hooks, Frontend]
7
category: "Web Development"
8
licenseName: "MIT"
9
author: "李四"
10
sourceLink: "https://github.com/lisi/react-hooks-guide"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: './react-hooks-cover.png'
15
  alt: 'React Hooks深度解析封面'
16
pubDate: 2025-01-20
17
---
18

19
# React Hooks深度解析
20

21
![React Hooks示例](./example-diagram.png)
22

23
在这篇文章中，我们将深入探讨React Hooks...

预览文章#

保存文件后，可以在浏览器中预览文章。将文件夹名拼接到预览URL的末尾即可查看。 例如，如果本地开发服务器运行在http://localhost:4321/，文件夹名为my-complex-post，则可以通过http://localhost:4321/posts/my-complex-post访问文章。

如果文章尚未创建或文件夹名错误，页面将显示404错误。当你预览一个尚未创建的文章时，控制台会显示不同的输出，这有助于进行故障排查。

链接到文章#

要在博客页面或其他页面中链接到你的文章，可以使用标准的HTML <a> 标签：

1
<a href="/posts/my-complex-post/">我的复杂文章</a>

确保链接的href属性指向正确的文章路径。

管理图片和其他资源#

使用这种方法，你可以将文章相关的所有资源都放在同一个文件夹中，便于管理：

1
src/content/posts/my-complex-post/
2
├── index.md
3
├── image1.png
4
├── image2.jpg
5
└── data.json

在文章中引用图片时，可以直接使用相对路径：

1
![图片描述](image1.png)

注意像这样直接填写文件的名字,这样才能让RSS正常构建图片的路径

创建多篇文章#

你可以在src/content/posts/目录下创建多个文件夹，每个文件夹代表一篇文章。例如：

1
src/content/posts/
2
├── my-first-post/
3
│   ├── index.md
4
│   └── cover.jpg
5
├── my-second-post/
6
│   ├── index.md
7
│   ├── image1.png
8
│   └── image2.png
9
└── my-third-post/
10
    ├── index.md
11
    └── data.json

每篇文章都有自己的独立文件夹，便于管理和维护。

链接多篇文章#

要在博客页面中链接到多篇文章，可以创建一个文章列表：

1
<ul>
2
  <li><a href="/posts/my-first-post/">我的第一篇文章</a></li>
3
  <li><a href="/posts/my-second-post/">我的第二篇文章</a></li>
4
  <li><a href="/posts/my-third-post/">我的第三篇文章</a></li>
5
</ul>

确保每个链接都指向正确的文章路径。

优势#

• 所有文章资源集中管理，便于维护
• 图片引用更简单，使用相对路径即可
• 更好的组织结构，特别是对于包含大量资源的文章
• 便于文章的迁移和备份
• 每篇文章都有独立的文件夹，避免资源混淆

文章客户端加密#

概述#

主题使用了 bcryptjs 用于密码的哈希处理，以及 crypto-js 用于内容的对称加密。

工作流程#

这一阶段发生在访客的浏览器里，当他们访问那个被加密的页面时：

使用方法#

在文章的 Front Matter 中添加以下配置：

1
---
2
title: '这是一篇加密文章'
3
encrypted: true
4
password: 'your-secret-password'
5
---

这样定义后就可以实现为文章设定不可逆的文章加密，只有输入正确的密码才能查看文章内容。

Mermaid图表#

我们可以使用mermaid语法来在文章中绘制图表

1
    ```mermaid
2
    graph TD
3
        A[Start] --> B{Condition Check}
4
        B -->|Yes| C[Process Step 1]
5
        B -->|No| D[Process Step 2]
6
        C --> E[Subprocess]
7
        D --> E
8
        subgraph E [Subprocess Details]
9
            E1[Substep 1] --> E2[Substep 2]
10
            E2 --> E3[Substep 3]
11
        end
12
        E --> F{Another Decision}
13
        F -->|Option 1| G[Result 1]
14
        F -->|Option 2| H[Result 2]
15
        F -->|Option 3| I[Result 3]
16
        G --> J[End]
17
        H --> J
18
        I --> J