# EasyBlog

**Repository Path**: fasterfish/EasyBlog

## Basic Information

- **Project Name**: EasyBlog
- **Description**: No description available
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-04-14
- **Last Updated**: 2024-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blog

📘[Englisth](./README.md)   📘[中文](./README-cn.md)

本博客系统通过构建工具生成`纯静态`的博客网站，借助`GitHub Pages`，你可以在5分钟内免费拥有个人博客。 它具有以下特点

- 生成纯静态网站，访问速度极快
- 使用markdown格式来编写博客内容
- 基于git代码管理来存储你的博客
- 使用CI工具来自动化部署你的博客站点

效果展示：[NilTor's Blog](https://blog.dusi.dev/)

## 🎖️功能

- 主页博客列表，支持搜索和分类和存档筛选
- 自定义网站名称和说明
- 随系统变化的Light和Dark主题
- 移动端的自适应显示
- TOC支持
- mermaid,nomnoml,Math的渲染支持
- 代码高亮及复制支持

## 使用Github Page部署

### Fork并配置GitHub Page

1. 点击`Fork`按钮，并创建自己的仓库。 并取消选择 Copy the main branch only。
2. 进入自己的GitHub仓库，点击`Actions`，启用workflows。
3. 点击`Settings`，找到Pages配置，在Build and deployment 选项中选择`GitHub Actions`.

### 配置

你可以通过根目录下的`webinfo.json`，对博客基础信息进行配置，如下所示：

```json
{
  "Name": "Niltor Blog", // 博客名称，显示在主页顶部导航
  "Description": "🗽 for freedom",// 说明，显示在主页顶部中间
  "AuthorName": "Ater", // 作者名称，显示在博客列表
  "BaseHref": "/blazor-blog/", // 子目录
  "Domain": "https://aterdev.github.io" // 域名，生成sitemap使用，不生成则留空
}
```

当你使用Github Page或使用IIS子应用部署时，需要调整`BaseHref`。通常是你的**项目名称**或**子目录名**。

> [!IMPORTANT]
> 注意，`BaseHref`尾部的`/`是必需的。
>
> 如果你配置了自定义域名，并且没有使用子目录，请将BaseHref设置为`/`。

修改后提交代码，GitHub会触发Action自动构建。

### 编写博客

请使用任何你习惯的markdown编辑器编写博客,唯一的要求是将博客内容放到`Content`目录下。你可以在该目录下创建多级目录。

### 发布博客

你只需要正常提交代码即可，github action会自动构建并最终发布你的博客，发布成功后可打开您的 GitHub Page 查看。

## 部署到其他服务

如果你不使用Github Page，那么你也可以轻松的部署到其他服务。核心的步骤只需要两步。

### 生成静态内容

`BuildSite`项目是用来将markdown转换成html的，请在根目录执行:

```pwsh
 dotnet run --project .\src\BuildSite\ .\Content .\WebApp Production
```

其中`.\Content`是你的markdown存储目录，`.\WebApp`是生成的静态站点目录。

### 上传到你的服务器

将`WebApp`中的所有文件复制到你的服务器即可。

> [!TIP]
> 根目录下的`publishToLocal.ps1`脚本可以自动完成构建和生成的操作，最终内容将在根目录下`WebApp`目录中。
>
> 如果你使用自动化部署，可参考.github/workflows中的脚本。

## 更新

上游代码的更新以`dev`分支为准，你可以将`dev`分支合并到你的`dev`分支，以获取最新的代码更新。

`main`作为默认的构建发布的分支，请不要合并到你的`main`分支。

建议您使用`dev`或其他自己的分支来编写博客和自定义内容，然后再合并到`main`分支以触发自动构建。

## 二次开发

fork之后，你将拥有所有的自定义权限，因为所有的源代码都已经在你自己的仓库中。

核心项目为`BuildSite`，用来生成静态文件，其中包括将markdown文件转换成html文件。

> [!NOTE]
> 建议创建自己的分支来自定义开发内容，方便后续的合并。

### 开发环境

`BuildSite`项目是一个.NET项目，你需要安装.NET SDK 8.0。

此外，你可以安装(可选)

- http-server，用来启动本地静态内容，以便调试。
- tailwindcss，用来生成css样式内容。
- typescript，以便使用`tsc`命令。

### 运行项目

1. 预览项目
   1. 打开终端，在`WebApp`目录下执行`http-server`，然后在浏览器中打开`http://127.0.0.1:8080`。
2. 生成静态内容。
   1. 在根目录下执行`dotnet run --project ./src/BuildSite ./Content ./WebApp`，以生成最新的静态内容。
   2. 或者直接运行根目录下的`build.ps1`脚本。
3. 刷新浏览器，可看到最新生成的内容。

> [!TIP]
> 如果你使用`Tailwindcss`，可在`WebApp`下执行`npx tailwindcss -o ./css/app.css --watch`。
>
> 如果你使用`Typescript`，可在`WebApp`下执行`tsc -w`。

### 自定义主页内容

主页内容模板位于`src\BuildSite\template\index.html.tpl`，其中包括以下变量：

|模板变量  |说明  |
|---------|---------|
|@{BaseUrl}   |  基础路径       |
|@{Name} |       博客名称  |
|@{Description} |    描述     |
|@{blogList} |    博客列表     |
|@{siderbar} |    侧边栏内容:分类和存档    |

你可以按照自己的想法修改主页的布局和样式。

> [!NOTE]
> 请注意标签中的`id`属性，`js`脚本将依赖于这些id标识，如果你修改了这些标识，同时要修改`js`脚本。

主页内容包括博客的搜索和分类筛选功能，其功能代码在`WebApp\js\index.js`中。

关于博客列表和分类列表的自定义，你可以参考`BuildSite`项目中`HtmlBuilder.cs`文件中的`GenBlogListHtml`和`GenSiderBar`方法。

后续我们会提供更灵活的自定义方式。

### 自定义博客展示页

博客页内容模板位于`src\BuildSite\template\blog.html.tpl`，其中包括以下变量：

|模板变量  |说明  |
|---------|---------|
|@{BaseUrl}   |  基础路径       |
|@{Title} |      页面标题  |
|@{content} |    博客内容     |
|@{toc} |   二级标题TOC    |

关于博客展示页的内容，你可以通过`WebApp/css/markdown.css`来修改样式，以及`WebApp/js/markdown.js`来定义逻辑。

### 自定义代码高亮

本项目使用`ColorCode`来格式化markdown中的代码内容，`ColorCode`使用正则来匹配代码内容。如果你需要对代码高亮进行定义，你需要：

- 添加或修改正则规则，你将在`ColorCode.Core/Compilation/Languages`目录下找到相应的语言定义，如果不存在，你可以添加新的语言支持。
- 如果是新添加的语言，需要在`ColorCode.Core/Languages.cs`中加载该语言。

> [!IMPORTANT]
> 如果你修改了`BuildSite`项目上中的代码，需要重新生成静态网站，才能看到最新效果。