【.NET項目分享】免費開源的靜態博客生成工具EasyBlog,5分鐘擁有自己的博客

EasyBlog 說明

本博客系統通過構建工具生成純靜態的博客網站，藉助GitHub Pages，你可以在5分鐘內免費擁有個人博客。 它具有以下特點

• 生成純靜態網站，訪問速度極快
• 使用markdown格式來編寫博客內容
• 基於git代碼管理來存儲你的博客
• 使用CI工具來自動化部署你的博客站點

效果展示：NilTor's Blog

開源地址

視頻介紹

🎖️功能

• 主頁博客列表，支持搜索和分類和存檔篩選
• 自定義網站名稱和說明
• 隨系統變化的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，對博客基礎信息進行配置，如下所示：

{
  "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的，請在根目錄執行:

 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，其中包括以下變量：

模板變量	說明
@	基礎路徑
@	博客名稱
@	描述
@	博客列表
@	側邊欄內容:分類和存檔

你可以按照自己的想法修改主頁的佈局和樣式。

[!NOTE]
請注意標籤中的id屬性，js腳本將依賴於這些id標識，如果你修改了這些標識，同時要修改js腳本。

主頁內容包括博客的搜索和分類篩選功能，其功能代碼在WebApp\js\index.js中。

關於博客列表和分類列表的自定義，你可以參考BuildSite項目中HtmlBuilder.cs文件中的GenBlogListHtml和GenSiderBar方法。

後續我們會提供更靈活的自定義方式。

自定義博客展示頁

博客頁內容模板位於src\BuildSite\template\blog.html.tpl，其中包括以下變量：

模板變量	說明
@	基礎路徑
@	頁面標題
@	博客內容
@	二級標題TOC

關於博客展示頁的內容，你可以通過WebApp/css/markdown.css來修改樣式，以及WebApp/js/markdown.js來定義邏輯。

自定義代碼高亮

本項目使用ColorCode來格式化markdown中的代碼內容，ColorCode使用正則來匹配代碼內容。如果你需要對代碼高亮進行定義，你需要：

• 添加或修改正則規則，你將在ColorCode.Core/Compilation/Languages目錄下找到相應的語言定義，如果不存在，你可以添加新的語言支持。
• 如果是新添加的語言，需要在ColorCode.Core/Languages.cs中加載該語言。

[!IMPORTANT]
如果你修改了BuildSite項目上中的代碼，需要重新生成靜態網站，才能看到最新效果。