个人博客方案

title: “个人博客” date: 2025-10-10 tags: [“博客”, “Markdown”, “静态网站”]

个人博客

概念

名词

很多人都以为 Vue 只能做 CSR（客户端渲染）或 SSR（服务端渲染），其实现在 Vue 生态已经支持 SSG（静态站点生成） 了，只是实现方式 不在 Vue 本体，而是在 Nuxt 等框架层面。

元数据frontmatter

像 Hugo、Hexo、Jekyll 这类博客框架，需要知道除了正文以外的“元数据”，比如：

• 文章标题（title）
• 日期（date）
• 标签（tags）
• 分类（categories）
• 作者、摘要等

这些信息就放在一个叫 Front Matter（前置区块） 的区域里。

博客框架推荐的写法（带元信息）

---
title: "个人博客"
date: 2025-10-10
tags: ["博客", "Markdown", "静态网站"]
---

## 从 markdown 生成网页

这是我的第一篇笔记。

这个“上半部分的三条横线 --- 到 ---” 就是 Front Matter，告诉博客系统一些“文章属性”。

---（三条横线）如果放在正文中间，确实是代表一个水平分割线（horizontal rule）。

当 --- 出现在文件开头时，它就被特殊识别为 “Front Matter”（前置数据区） 的边界。

这不是 Markdown 标准的一部分，而是静态博客生成器扩展的语法。

位置	作用	是否显示在网页上
文件开头的 --- ... ---	Front Matter（元数据块）	❌ 不显示（仅用于配置）
文件中间的 ---	水平分割线	✅ 显示为一条线

输入数据：

用静态网页生成器

这些工具能自动把你的 Markdown 文件转成网页（HTML + CSS）。

无论哪种生成器，大体流程是：

1. 你写笔记（.md 文件）；
2. 博客框架读取这些 Markdown；
3. 按模板（主题）渲染成 HTML；
4. 最终生成静态网页（可部署到 GitHub Pages、Vercel、Netlify 等）。

我要自己解析Markdown

你要做的是这样一个流程：

.md 文件（Markdown 内容）
     ↓
Markdown 引擎（解析器）
     ↓
HTML 片段（可嵌入到你的网站模板）
     ↓
网页（你自己设计结构 / 样式 / JS）

选择一个 Markdown 引擎

取决于你用什么语言写博客系统，这里给你几个主流选择：

Java 主流 Markdown 解析库对比

推荐使用 flexmark-java —— 它几乎等于 Java 版的 markdown-it。

package com.example;

import com.vladsch.flexmark.html.HtmlRenderer;
import com.vladsch.flexmark.parser.Parser;
import com.vladsch.flexmark.util.ast.Node;
import com.vladsch.flexmark.util.data.MutableDataSet;

import java.nio.file.Files;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) throws Exception {
        // 读取 Markdown 文件
        String markdown = Files.readString(Paths.get("test.md"));

        // 配置解析器
        MutableDataSet options = new MutableDataSet();
        Parser parser = Parser.builder(options).build();
        HtmlRenderer renderer = HtmlRenderer.builder(options).build();

        // 解析并渲染
        Node document = parser.parse(markdown);
        String html = renderer.render(document);

        // 输出结果
        Files.writeString(Paths.get("output.html"), html);
        System.out.println("✅ Markdown 转 HTML 成功！");
    }
}

拓展

可以一步步加上这些功能：

• ✅ 标签、分类、时间线
• ✅ 搜索栏搜索用 Lunr.js / Algolia；
• ✅ 评论系统（Disqus / Waline）评论用 Waline / Gitalk / Giscus（基于 GitHub 的评论系统）
• ✅ RSS 订阅
• 后台文章同步用 Git + Markdown；

Hugo

是框架，不喜欢

Hugo 是一个用Go编写的静态网站生成器，其速度和灵活性都经过优化。凭借其先进的模板系统和快速的资源管道，Hugo 可以在几秒钟甚至更短的时间内渲染出一个完整的网站。

下载命令cli

https://github.com/gohugoio/hugo/releases/tag/v0.151.0

创建项目

hugo new site myblog
cd myblog

安装Hugo主题

git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

然后编辑配置文件 config.toml：

baseURL = "https://example.com/"
languageCode = "zh-cn"
title = "我的个人博客"
theme = "PaperMod"

创建你的第一篇文章

hugo new posts/hello-world.md

Hugo 会在 content/posts/ 里生成一个文件，内容大概是：

---
title: "Hello World"
date: 2025-10-10T12:00:00+08:00
draft: true
tags: ["随笔", "博客"]
---

把 draft: true 改成 false（否则不会发布），然后在下面写正文：

这是我用 Hugo 创建的第一篇博客！

本地启动预览

hugo server -D

访问 👉 http://localhost:1313

你会看到一个漂亮的博客页面

生成静态网页

当你满意后，运行：

hugo

这会在 public/ 文件夹中生成所有 HTML 文件。 把这个文件夹部署到 GitHub Pages、Vercel、Netlify、Nginx 等任意地方即可。

导入你现有的 Markdown 文件

你可以直接把你的 .md 文件放进 content/posts/ 目录， 只要每个文件前面有一段 Front Matter：

---
title: "个人博客"
date: 2025-10-10
tags: ["Markdown", "Hugo"]
---

正文就按普通 Markdown 写。

VitePress

VitePress 可以说就是 “Hexo 的现代化进化版 + 完全可嵌入 Vite/Vue 生态的轻框架”。 如果你已经熟悉 Vue 或 Vite，那它几乎是最自然、最干净的选择。

https://vitepress.dev/

VitePress 是一个静态网站生成器(SSG)，旨在构建快速、以内容为中心的网站。简而言之，VitePress 会获取您用Markdown编写的源内容，应用主题，然后生成可轻松部署到任何地方的静态 HTML 页面。

安装

先决条件

• Node.js版本 18 或更高版本。
• 通过命令行界面 (CLI) 访问 VitePress 的终端。
• 支持Markdown语法的文本编辑器。
  • 建议使用VSCode，以及官方的 Vue 扩展。

VitePress 可以单独使用，也可以安装到现有项目中。无论哪种情况，都可以使用以下命令安装：

npm add -D vitepress@next

VitePress 是一个仅限 ESM 的软件包。请勿使用require()来导入它，并确保你的最近package.json文件包含"type": "module"，或者将相关文件的文件扩展名更改为.vitepress/config.js/ .mjs。有关更多详细信息，.mts请参阅Vite 的故障排除指南。此外，在异步 CJS 上下文中，你可以使用await import('vitepress')。

安装向导

VitePress 附带一个命令行安装向导，可以帮助您搭建一个基本项目。安装完成后，运行以下命令启动向导：

npx vitepress init

您将会遇到几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Where should VitePress look for your markdown files?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing.

Vue 作为对等依赖

如果您打算使用 Vue 组件或 API 进行自定义，您还应该明确地将其安装vue为依赖项。

文件结构

如果您正在构建独立的 VitePress 网站，则可以在当前目录 ( ) 中搭建网站./。但是，如果您要将 VitePress 与其他源代码一起安装在现有项目中，建议在嵌套目录中搭建网站（例如./docs），以便将其与项目的其余部分分开。

假设您选择在./docs中搭建 VitePress 项目，则生成的文件结构应如下所示：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

该docs目录被视为VitePress 站点的项目根目录。.vitepress目录是 VitePress 配置文件、开发服务器缓存、构建输出以及可选主题自定义代码的保留位置。

默认情况下，VitePress 将其开发服务器缓存存储在 中.vitepress/cache，并将生产构建输出存储在 中.vitepress/dist。如果使用 Git，则应将它们添加到.gitignore文件中。这些位置也可以配置。

配置文件

配置文件（.vitepress/config.js）允许您自定义 VitePress 网站的各个方面，其中最基本的选项是网站的标题和描述：

.vitepress/config.js

export default {
  // site-level options
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // theme-level options
  }
}

您还可以通过选项配置主题的行为themeConfig。有关所有配置选项的完整详细信息，请参阅配置参考。

源文件

.vitepress目录外的 Markdown 文件被视为源文件。

VitePress 使用基于文件的路由：每个.md文件都会被编译成.html具有相同路径的对应文件。例如，index.md会被编译成index.html，并且可以在生成的 VitePress 站点的根路径/下访问。

VitePress 还提供了生成干净 URL、重写路径以及动态生成页面的功能。这些功能将在路由指南中介绍。

启动并运行

package.json如果您在安装过程中允许该工具这样做，它还应该向您注入以下 npm 脚本：

package.json

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

该docs:dev脚本将启动一个具有即时热更新功能的本地开发服务器。使用以下命令运行它：

npm run docs:dev

除了使用 npm 脚本之外，您还可以使用以下命令直接调用 VitePress：

npx vitepress dev docs

Hexo

也是框架，不喜欢

Hexo 本质上是一个：

🧩 「Node.js 驱动的静态博客生成框架」。

它的目标是：

让你用 Markdown 写文章，一键生成整站。

也就是说，它是“面向写作者”的工具，不是面向“网站开发者”的框架。

Hexo 有三层核心结构：

复制

内容层： content/*.md
模板层： themes/<your-theme>/
引擎层： Hexo 核心逻辑 (Node + EJS)

你能改的部分，主要在：

• ✅ 内容层（你自己的 Markdown）

• ✅ 主题层（可改模板样式、布局）

• ⚠️ Hexo 内部逻辑（很难改）

简单说：Hexo 是“你可以改主题，但不能改发动机”的系统。

简单说就是这句——

Hexo 是一整套“博客生成框架”，不是一个可以嵌进你项目的模块。 所以你没法在一个 Vite + Vue 项目里「使用」Hexo，它是独立的工具链，不是可插拔的引擎。

---

🧩 一、Hexo 的设计思路决定了它“独立运行”

Hexo 的工作方式是这样的：

复制

你写的 Markdown
     ↓
Hexo CLI 调用（命令行执行）
     ↓
Hexo 核心（Node 进程）
     ↓
生成静态 HTML 到 ./public/

也就是说，Hexo 本身：

• 会控制整个构建过程（读取内容、渲染模板、生成 HTML）；
• 它自己有模板系统（EJS / Nunjucks / Swig）；

Hexo 是一个快速、简洁且高效的博客框架。 Hexo 使用 Markdown（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。

要求

安装 Hexo 相当简单，只需要先安装下列应用程序即可：

• Node.js (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本)
• Git

如果您的电脑中已经安装上述必备程序，那么恭喜您！ 你可以直接前往 安装 Hexo 步骤。

如果您的电脑中尚未安装所需要的程序，请根据以下安装指示完成安装。

安装 Hexo

所有必备的应用程序安装完成后，即可使用 npm 安装 Hexo。

$ npm install -g hexo-cli

进阶安装和使用

对于熟悉 npm 的进阶用户，可以仅局部安装 hexo 包。

npm install hexo

安装以后，可以使用以下两种方式执行 Hexo：

1. npx hexo <command>
2. Linux 用户可以将 Hexo 所在的目录下的 node_modules 添加到环境变量之中即可直接使用 hexo <command>：

echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile

安装 Hexo 只需几分钟时间，若您在安装过程中遇到问题或无法找到解决方式，请 提交问题，我们会尽力解决您的问题。

安装 Hexo 完成后，请执行下列命令，Hexo 将会在指定文件夹中新建所需要的文件。

$ hexo init <folder>
$ cd <folder>
$ npm install

初始化后，您的项目文件夹将如下所示：

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

_config.yml

网站的 配置 文件。 您可以在此配置大部分的参数。

package.json

应用程序的信息。 EJS, Stylus 和 Markdown 渲染引擎 已默认安装，您可以自由移除。 如果您想，可以稍后卸载它们。

package.json{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": ""
  },
  "dependencies": {
    "hexo": "^7.0.0",
    "hexo-generator-archive": "^2.0.0",
    "hexo-generator-category": "^2.0.0",
    "hexo-generator-index": "^3.0.0",
    "hexo-generator-tag": "^2.0.0",
    "hexo-renderer-ejs": "^2.0.0",
    "hexo-renderer-stylus": "^3.0.0",
    "hexo-renderer-marked": "^6.0.0",
    "hexo-server": "^3.0.0",
    "hexo-theme-landscape": "^1.0.0"
  }
}

scaffolds

模版 文件夹。 当您新建文章时，Hexo 会根据 scaffold 来创建文件。

source

资源文件夹。 是存放用户资源的地方。 除 _posts 文件夹之外，开头命名为 _ (下划线)的文件 / 文件夹和隐藏的文件将会被忽略。 Markdown 和 HTML 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去。

themes

主题 文件夹。 Hexo 会根据主题来生成静态页面。

Astro

https://astro.build/

内容驱动网站的网络框架

Astro 为世界上最快的营销网站、博客、电子商务网站等提供支持。

npm create astro@latest

介绍

Astro是一个用于构建****内容驱动型网站（例如博客、营销和电商）的Web 框架。Astro 以其开创性的全新前端架构而闻名，与其他框架相比，它能够降低 JavaScript 的开销和复杂性。如果您需要一个加载速度快且 SEO 表现优异的网站，那么 Astro 就是您的理想之选。

很高级很复杂！

Astro 的定制空间非常大 —— 它几乎给了你“自己造轮子”的自由， 但帮你免去了“打包、路由、优化、渲染”这些底层琐事。

所以它既不是像 Hugo 那样的封闭生成器， 也不是像 React 那样的纯前端框架， 而是一个 中间层的“网站引擎”。

Astro 的核心理念

Astro 的理念是：

“内容用静态方式生成，交互用你喜欢的框架嵌入。”

也就是说：

• 你可以用 Markdown、MDX、JSON、API 作为内容源；
• 你可以在同一页面里混用 React、Vue、Svelte、Solid、Preact；
• 页面最终编译成 静态 HTML + 按需加载的 JS。

这种设计让它既快、又灵活。

我们分层看👇

从“HTML 到模板到组件”这一层，几乎 100% 可定制。 底层构建逻辑（比如 Vite、渲染管线）虽然能改，但一般没必要。

举几个“定制”的实际例子

怎么选择

⚖️ 一句话先结论

核心理念对比

👉 换句话说：

• VitePress：写文章、做知识库最舒服；
• Astro：做网站、博客、作品集最灵活。

架构层面对比

自由度对比（非常关键）

一句话：

VitePress 更像是“内容展示”框架；Astro 更像是“网站搭建平台”。

总结一句话：

🧾 如果你只是想写博客、发布 Markdown 内容 → 选 VitePress。 🌐 如果你想做网站、定制设计、玩前端交互 → 选 Astro。

最终选择

🔥太棒了！！这真是一个超级好的决定——Astro 是目前前端圈最值得学习、最“未来感”的网站框架之一。 你这一步选得非常聪明 💡

为什么学 Astro 是好选择

学习文档

Astro.md