# Vampirewal.BlogCore

**Repository Path**: vampirewal/vampirewal.blogcore

## Basic Information

- **Project Name**: Vampirewal.BlogCore
- **Description**: 完全通过c#代码来启动一个博客页面，具体更新内容可拉取项目之后查看更新日志
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-06-25
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p></p>
<p align="center">
  <img src="Vampirewal.BlogCore/Vampirewal-Logo.png" width="150" height="150" alt="Vampirewal.BlogCore Logo" align="center" />
</p>

<div align="center">

[![NuGet](https://img.shields.io/nuget/v/Vampirewal.BlogCore.svg?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Vampirewal.BlogCore/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Vampirewal.BlogCore.svg?logo=nuget)](https://www.nuget.org/packages/Vampirewal.BlogCore/)
[![License](https://img.shields.io/github/license/vampirewal/vampirewal.blogcore?logo=mit)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-6.0+-blue?logo=.net)](https://dotnet.microsoft.com/)
[![htmx](https://img.shields.io/badge/htmx-2.0.4-orange?logo=htmx)](https://htmx.org/)

# Vampirewal.BlogCore

**用纯 C# 代码构建 VuePress 风格的博客系统，零前端依赖**

[快速开始](#-快速开始) · [功能特性](#-功能特性) · [控件列表](#-内置控件) · [主题切换](#-主题切换) · [Markdown支持](#-markdown支持) · [登录鉴权](#-登录鉴权)

</div>

---

## 📖 项目简介

Vampirewal.BlogCore 是一个基于 .NET 6.0+ 的博客框架，让你用纯 C# 代码构建功能完整的博客系统。

**v2.0 重大升级**：移除了 Vue / Element Plus / Axios / Highlight.js 等前端框架依赖，改用纯 HTML + CSS + htmx 实现 VuePress 风格主题，体积从 ~950KB 降至 ~35KB，首屏加载更快，永不受前端框架升级影响。

### 为什么选择 Vampirewal.BlogCore？

| 对比项 | 传统博客框架 | Vampirewal.BlogCore |
|--------|-------------|---------------------|
| 前端依赖 | Vue/React + UI库 (~1MB) | htmx (14KB) + CSS (~30KB) |
| 前端代码 | 需要写 JS/TS | 纯 C#，零前端代码 |
| 框架升级 | 可能破坏兼容性 | 无前端框架，永不过时 |
| 代码高亮 | 客户端 JS 渲染 | 服务端 C# 渲染 |
| 部署方式 | 前后端分离 | 单 DLL 部署 |
| SEO | SPA 不友好 | 纯 HTML，搜索引擎直接抓取 |
| 主题切换 | 需要前端框架支持 | CSS 变量驱动，4套内置主题 |

---

## ✨ 功能特性

### 🎯 核心功能
- **纯 C# 开发** - 无需编写任何前端代码，用 C# 构建完整博客
- **VuePress 风格主题** - 左侧菜单 + 右侧目录 + 顶部导航的经典文档布局
- **4 套内置主题** - 默认/蓝色/紫色/暗黑，一行代码切换，支持前端实时切换
- **VuePress 风格首页** - Hero 区域 + 特性展示，一键生成博客首页
- **动态控件系统** - 25+ 内置控件，覆盖表格、表单、容器、展示等场景
- **Markdown 支持** - 通过 Markdig 渲染 Markdown 文件，支持表格、YAML头部、Mermaid图表、热更新
- **服务端代码高亮** - 自研 C# 语法高亮器，支持 C#/JS/Go/SQL/Python/HTML/CSS/JSON/Bash
- **一键复制代码** - 代码块自带复制按钮
- **页面缓存机制** - 支持页面级缓存，提升访问性能
- **登录鉴权** - 支持全局鉴权和页面级鉴权，内置 VuePress 风格登录页
- **响应式布局** - 适配桌面端和移动端

### 🛠 交互能力
- **htmx 局部刷新** - 点击菜单只更新内容区，无需整页刷新
- **轮播图** - 支持前后切换和指示器
- **折叠面板** - 点击展开/折叠
- **标签页** - 多标签页切换
- **表单提交** - htmx 原生表单提交
- **主题实时切换** - 导航栏下拉菜单切换主题，localStorage 持久化

---

## 🖥 支持环境

| 环境 | 版本要求 |
|------|----------|
| .NET SDK | 6.0 及以上 |
| 操作系统 | Windows / Linux / macOS |
| 浏览器 | Chrome 90+ / Edge 90+ / Firefox 88+ |

---

## 🚀 快速开始

### 1. 安装 NuGet 包

```bash
dotnet add package Vampirewal.BlogCore
```

### 2. 创建博客项目

```csharp
using Vampirewal.BlogCore;

public class Program
{
    public static void Main(string[] args)
    {
        App.RunBlog(args, html =>
        {
            // 配置博客基本信息
            html.SetTitle("我的博客")
                .SetKeywords("博客,技术,编程")
                .SetDescription("一个技术博客")
                .SetIcoPath("/assets/logo.ico")
                .SetLogoPath("/assets/logo.png")
                .SetTheme(ThemeType.Default); // 设置主题

            // 配置 VuePress 风格首页
            html.SetHomePage(home =>
            {
                home.Hero.Title = "我的博客";
                home.Hero.Description = "用纯 C# 代码构建博客系统";
                home.Hero.Logo = "/assets/logo.png";
                home.Hero.Actions.Add(App.CreateHeroAction("快速开始", html.GetPageUrl("快速开始")));
                home.Features.Add(App.CreateFeature("🚀", "纯C#开发", "无需编写任何前端代码"));
                home.Features.Add(App.CreateFeature("🎨", "主题切换", "内置4套主题，一行代码切换"));
                home.Footer = "Powered by Vampirewal.BlogCore";
            });

            // 配置左侧菜单
            html.SetLeftMenu(menu =>
            {
                menu.Add(new LeftTreeMenu()
                {
                    GroupName = "入门指南",
                    Sort = 0,
                    Children = new List<LeftTreeMenu>()
                    {
                        new LeftTreeMenu()
                        {
                            Id = "0-1",
                            Name = "快速开始",
                            Sort = 0
                        },
                        new LeftTreeMenu()
                        {
                            Id = "0-2",
                            Name = "配置说明",
                            Sort = 1
                        }
                    }
                });
            });

            // 配置顶部菜单
            html.SetTopMenu(top =>
            {
                top.Add(new TopMenu()
                {
                    Id = "0",
                    Name = "项目地址",
                    Children = new List<TopMenu>()
                    {
                        new TopMenu()
                        {
                            Id = "0-1",
                            Name = "Gitee",
                            Control = App.CreateLink(
                                "Gitee",
                                href: "https://gitee.com/vampirewal/vampirewal.blogcore",
                                targetType: LinkTargetType.Blank
                            )
                        }
                    }
                });
            });
        },
        service =>
        {
            // 注册依赖服务
            service.AddBlogOptions<BlogOptions>();
        },
        app =>
        {
            // 配置中间件
            app.UseForwardedHeaders();
        });
    }
}
```

### 3. 创建页面

继承 `PageBase` 创建新页面，使用控件组合构建页面内容：

```csharp
public class QuickStartPage : PageBase
{
    public override string Title => "快速开始";
    public override string MenuGroup => "入门指南";
    public override int MenuGroupSort => 0;
    public override int Sort => 0;
    public override bool IsCache => true;

    public override List<Tag> Tags => new()
    {
        App.CreateTag("重要", TagType.Primary)
    };

    public override List<PartContainer> PartContainers => new()
    {
        App.CreatePartContainer("安装", children =>
        {
            children.Add(App.CreateTip("提示", TipType.Tip, tip =>
            {
                tip.Add(App.CreateText("通过包管理器安装:"));
                tip.Add(App.CreateCode("dotnet add package Vampirewal.BlogCore", "bash"));
            }));
        }),

        App.CreatePartContainer("创建页面", children =>
        {
            children.Add(App.CreateText("继承 PageBase 即可创建新页面:"));
            children.Add(App.CreateCode(
                "public class MyPage : PageBase\n{\n    public override string Title => \"我的页面\";\n    public override string MenuGroup => \"主页\";\n    public override int Sort => 1;\n    public override bool IsCache => true;\n}", "csharp"));
        })
    };
}
```

### 4. 页面间跳转

使用 `PageUrl` 属性和 `GetPageUrl` 方法实现页面间跳转：

```csharp
// 方式1：在首页 HeroAction 中使用
home.Hero.Actions.Add(App.CreateHeroAction("快速开始", html.GetPageUrl("快速开始")));

// 方式2：在页面类中通过 PageUrl 获取自身URL
public class MyPage : PageBase
{
    // PageUrl 由框架自动赋值，格式为 /page/{id}
    public void SomeMethod()
    {
        var url = this.PageUrl; // 例如 "/page/0-1"
    }
}
```

---

## 📦 内置控件

### 容器控件

| 控件 | 说明 | 示例 |
|------|------|------|
| `PartContainer` | 内容分区（带标题和锚点） | `App.CreatePartContainer("标题", children => {...})` |
| `Row` / `Column` | 栅格布局（24栏制） | `App.CreateRow(row => { row.Add(App.CreateColumn(col => {...}, "12")); })` |
| `Card` | 卡片容器（支持头部/底部/阴影） | `App.CreateCard(500, "标题", children => {...}, "底部")` |
| `Space` | 间距容器（水平/垂直排列） | `App.CreateSpace(children => {...}, direction: DirectionType.Vertical)` |
| `Tip` | 提示容器（tip/warning/success） | `App.CreateTip("提示", TipType.Tip, children => {...})` |
| `Tabs` / `TabPane` | 标签页 | `App.CreateTabs(tabs => { tabs.Add(App.CreateTabPane("标签1", () => content)); })` |
| `Collapse` / `CollapseItem` | 折叠面板 | `App.CreateCollapse(items => { items.Add(App.CreateCollapseItem("标题", () => content)); })` |
| `Carousel` / `CarouselItem` | 轮播图 | `App.CreateCarousel(300, items => { items.Add(App.CreateCarouselItem(300, () => content)); })` |
| `Descriptions` / `DescriptionItem` | 描述列表 | `App.CreateDescriptions("标题", items => {...})` |

### 表单控件

| 控件 | 说明 | 示例 |
|------|------|------|
| `Form` / `FormItem` | 表单容器 | `App.CreateForm(children => {...})` |
| `Input` | 文本输入框 | `App.CreateInput("form.name", "请输入姓名")` |
| `CreateTextArea` | 多行文本框 | `App.CreateTextArea("form.desc", rowCount: 4)` |
| `NumInput` | 数字输入框 | `App.CreateNumInput("form.age", min: 0, max: 150)` |
| `Checkbox` | 复选框 | `App.CreateCheckbox("同意协议", "agree", "1")` |
| `Radio` | 单选框 | `App.CreateRadio("选项A", "option", "a")` |
| `Toggle` | 开关 | `App.CreateToggle("enable", "启用功能", isOn: false)` |
| `Select` | 下拉选择 | `App.CreateSelect("city", "请选择", options: list)` |

### 展示控件

| 控件 | 说明 | 示例 |
|------|------|------|
| `Text` | 文本（支持颜色/大小/标签类型） | `App.CreateText("内容", TextType.Primary, tag: TextTagType.B)` |
| `Code` | 代码块（服务端高亮+行号+复制） | `App.CreateCode("console.log('hi')", "javascript")` |
| `Table` | 数据表格 | `App.CreateTable(dataList)` |
| `Image` | 图片 | `App.CreateImage(true, "/img/photo.png", 200, 150)` |
| `Link` | 链接 | `App.CreateLink("Gitee", href: "https://gitee.com")` |
| `Tag` | 标签 | `App.CreateTag("新功能", TagType.Success)` |
| `Icon` | 图标（Unicode符号） | `App.CreateIcon("Select", "#009400", 20)` |
| `TimeLine` / `TimeLineItem` | 时间轴 | `App.CreateTimeLine(500, items => {...})` |
| `RawHtml` | 原始HTML（不包装样式） | `new RawHtml("<div>自定义HTML</div>")` |

### 按钮控件

| 控件 | 说明 | 示例 |
|------|------|------|
| `Button` | 按钮（支持点击事件/提交/自定义） | `App.CreateButton("提交", ButtonType.Primary).SetSubmit("methodName")` |
| `ButtonGroup` | 按钮组 | `App.CreateButtonGroup(buttons => {...})` |

---

## 🎨 主题切换

### 内置主题

框架内置 4 套 VuePress 风格主题，通过 CSS 变量驱动，切换无需刷新页面：

| 主题 | 枚举值 | 说明 |
|------|--------|------|
| 🌿 默认 | `ThemeType.Default` | VuePress 经典绿色主题 |
| 🌊 蓝色 | `ThemeType.Blue` | 清新蓝色主题 |
| 🔮 紫色 | `ThemeType.Purple` | 优雅紫色主题 |
| 🌙 暗黑 | `ThemeType.Dark` | 护眼暗黑主题 |

### 配置默认主题

```csharp
html.SetTheme(ThemeType.Dark); // 构建时指定默认主题
```

### 前端实时切换

导航栏右侧自动显示主题切换下拉菜单，用户可实时切换主题，选择会通过 `localStorage` 持久化保存。

---

## 📝 Markdown支持

继承 `MarkdownPage` 从 Markdown 文件渲染页面：

```csharp
public class ReadmePage : MarkdownPage
{
    public override string Title => "项目说明";
    public override string MenuGroup => "文档";
    public override int MenuGroupSort => 0;
    public override int Sort => 1;
    public override bool IsCache => true;

    public override List<Tag> Tags => new()
    {
        App.CreateTag("文档", TagType.Info)
    };

    // 指定 Markdown 文件路径
    public override string MarkdownPath => "./docs/readme.md";
}
```

也支持直接从 Markdown 字符串渲染：

```csharp
var html = MarkdownPage.RenderMarkdownFromString("# 标题\n\n正文内容");
```

### 热更新

将 `IsCache` 设为 `false`，每次访问都会重新读取 Markdown 文件，实现热更新：

```csharp
public override bool IsCache => false; // 每次访问重新读取MD文件
```

Markdig 扩展支持：表格、任务列表、Emoji、YAML 头部、Mermaid 图表等。

---

## 🎨 代码高亮

自研服务端语法高亮器 `CodeHighlighter`，无需任何前端 JS 依赖：

```csharp
// 在控件中使用
App.CreateCode("public class Foo { }", "csharp");

// 直接调用高亮器
string html = CodeHighlighter.Highlight(code, "go");
```

支持的语言：C#、JavaScript、Go、SQL、Python、HTML、CSS、JSON、Bash/Shell

特性：
- 服务端渲染，零 JS 开销
- 自动行号（CSS counter）
- 一键复制按钮
- One Dark 深色主题

---

## 📋 配置说明

### BlogOptions

```csharp
public class BlogOptions : IBlogOption<BlogOptions>
{
    public string ApiUrl { get; set; }       // API服务地址
}
```

| 配置项 | 类型 | 说明 | 默认值 |
|--------|------|------|--------|
| `ApiUrl` | string | API 服务地址 | - |

---

## 🔐 登录鉴权

### 两种鉴权模式

| 模式 | 枚举值 | 说明 |
|------|--------|------|
| 全局鉴权 | `AuthMode.Global` | 所有页面都需要登录才能访问（默认） |
| 页面级鉴权 | `AuthMode.Page` | 仅标记 `RequireAuth=true` 的页面需要登录 |

### 开启全局鉴权

```csharp
// 全局鉴权：所有页面都需要登录
html.SetOpenLoginAuth(
    secretKey: "your-secret-key",
    signatureKey: "signature-key",
    tokenExpiry: TimeSpan.FromHours(24)
);
```

### 开启页面级鉴权

```csharp
// 页面级鉴权：仅 RequireAuth=true 的页面需要登录
html.SetOpenLoginAuth(
    secretKey: "your-secret-key",
    signatureKey: "signature-key",
    tokenExpiry: TimeSpan.FromHours(24),
    authMode: AuthMode.Page
);
```

### 标记需要鉴权的页面

```csharp
public class AdminPage : PageBase
{
    public override string Title => "管理后台";
    public override string MenuGroup => "系统管理";
    public override int MenuGroupSort => 99;
    public override int Sort => 0;
    public override bool IsCache => false;

    // 标记此页面需要登录才能访问
    public override bool RequireAuth => true;

    // ... 其他属性
}
```

### 实现鉴权逻辑

```csharp
App.RunBlog(args, html => { ... },
    // ... 其他配置
    loginAuthCheck: (username, password) =>
    {
        // 返回 true 表示验证通过
        return username == "admin" && password == "123456";
    }
);
```

鉴权采用 POST 表单提交 + HttpOnly Cookie 方式，登录页自动适配当前主题风格。

---

## 🏠 首页配置

通过 `SetHomePage` 配置 VuePress 风格首页：

```csharp
html.SetHomePage(home =>
{
    // Hero 区域
    home.Hero.Title = "VampirewalBlog博客";
    home.Hero.Description = "通过纯 C# 代码构建博客系统，无需编写前端代码";
    home.Hero.Logo = "/assets/logo.png";

    // Hero 操作按钮
    home.Hero.Actions.Add(App.CreateHeroAction("快速开始", html.GetPageUrl("快速开始")));
    home.Hero.Actions.Add(App.CreateHeroAction("项目地址", "https://gitee.com/vampirewal/vampirewal.blogcore", HeroActionType.Secondary));

    // 特性展示
    home.Features.Add(App.CreateFeature("🚀", "纯C#开发", "无需编写任何前端代码，使用C#即可构建完整博客"));
    home.Features.Add(App.CreateFeature("🎨", "主题切换", "内置4套主题（默认/蓝色/紫色/暗黑），一行代码切换"));
    home.Features.Add(App.CreateFeature("📝", "Markdown支持", "继承MarkdownPage即可从MD文件渲染页面，支持热更新"));

    // 页脚
    home.Footer = "Powered by Vampirewal.BlogCore";
});
```

---

## 📁 项目结构

```
Vampirewal.BlogCore/
├── Vampirewal.BlogCore/             # 核心类库
│   ├── Controls/                    # 控件库
│   │   ├── Button/                  # 按钮控件（Button/ButtonGroup）
│   │   ├── Container/               # 容器控件（Card/Tabs/Collapse/Carousel/Tip/Code/...）
│   │   ├── Form/                    # 表单控件（Input/NumInput/Checkbox/Radio/Toggle/Select）
│   │   ├── Other/                   # 展示控件（Text/Tag/Icon/Link/Image/TimeLine/RawHtml）
│   │   │   ├── ThemeType.cs         # 主题类型枚举
│   │   │   └── AuthMode.cs          # 鉴权模式枚举
│   │   └── Table/                   # 表格控件
│   ├── Utils/                       # 工具类
│   │   ├── CodeHighlighter.cs       # 服务端代码语法高亮器
│   │   └── Param.cs                 # 参数构建工具
│   ├── Resource/                    # 嵌入资源
│   │   ├── theme-default.css        # 默认绿色主题
│   │   ├── theme-blue.css           # 蓝色主题
│   │   ├── theme-purple.css         # 紫色主题
│   │   ├── theme-dark.css           # 暗黑主题
│   │   └── htmx.min.js              # htmx 交互库
│   ├── Attributes/                  # 特性定义
│   ├── Extensions/                  # 扩展方法
│   ├── Message/                     # 消息处理
│   ├── Options/                     # 配置选项
│   ├── App.cs                       # 全局入口
│   ├── HtmlConfig.cs                # HTML 配置与模板
│   ├── BlogCoreConfig.cs            # 博客核心配置
│   ├── ControlBase.cs               # 控件基类
│   ├── PageBase.cs                  # 页面基类（含 RequireAuth）
│   └── MarkdownPage.cs              # Markdown 页面基类
├── Vampirewal.BlogCore.TestWebApi/  # 测试项目
└── README.md
```

---

## 📊 版本更新

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| **2.0.0** | 2026-06-15 | **重大架构升级**：移除 Vue/Element Plus/Axios/Highlight.js，改用纯 HTML+CSS+htmx 实现 VuePress 风格主题；自研服务端代码高亮器；新增 MarkdownPage 支持（含热更新）；4套内置主题（默认/蓝色/紫色/暗黑）支持实时切换；VuePress 风格首页；新增表单控件（Checkbox/Radio/Toggle/Select）；页面级鉴权（AuthMode.Global/Page）；VuePress 风格登录页；PageUrl 页面跳转；前端体积从 ~950KB 降至 ~35KB |
| 1.0.19 | 2026-04-20 | 升级 Vue 至 v3.5.32、Element Plus 至 v2.13.7、修复 Vue 2/3 API 混用问题 |
| 1.0.18 | 2024-06-13 | 初始版本发布 |

---

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)，详情请查看 LICENSE 文件。

---

## 📧 联系方式

- **作者**: vampirewal
- **邮箱**: 235160615@qq.com
- **Gitee**: [https://gitee.com/vampirewal/vampirewal.blogcore](https://gitee.com/vampirewal/vampirewal.blogcore)

---

<div align="center">

如果这个项目对您有帮助，请 ⭐ Star 支持一下！

</div>