Merge branch 'dev'

AterDev · Jul 17, 2024 · 8547a0b · 8547a0b
2 parents 4b51f97 + e3c75a6
commit 8547a0b
Show file tree

Hide file tree

Showing 18 changed files with 581 additions and 156 deletions.
diff --git a/README.md b/README.md
@@ -2,12 +2,13 @@
 
 📘[Englisth](./README.md)   📘[中文](./README_cn.md)
 
-This blog system generates a **pure static** blog website through build tools. With the help of **GitHub Pages**, you can have a personal blog for free in 5 minutes. It has the following features:
+This tool generates a `pure static` blog website from a `markdown` document through commands. With the help of `GitHub Pages`, you can have a personal blog for free in 5 minutes.It has the following characteristics
 
-- Generate pure static websites for extremely fast access speed
-- Use markdown format to write blog content
-- Use git code management to store your blog
-- Use CI tools to automatically deploy your blog site
+- Provide command line tools to generate static websites
+- Generate a pure static website with extremely fast access speed
+- Support for content written in markdown format
+- Support search, classification, archiving and screening
+- Customize website name and description, etc
 
 **Demo:** NilTor's Blog: [https://blog.dusi.dev/](https://blog.dusi.dev/)
 
@@ -21,75 +22,143 @@ This blog system generates a **pure static** blog website through build tools. W
 - mermaid, nomnoml, Math rendering support
 - Code highlighting and copy support
 
-## Deploy with Github Page
+## 🚀Quick Start
 
-### Fork and configure GitHub Page
+Currently, the tool has been released in the form of 'dotnet tool'.You can easily install and use it.
 
-1. Click the **Fork** button and create your own repository. Uncheck **Copy the main branch only**.
-2. Go to your own GitHub repository, click **Actions**, and enable workflows.
-3. Click **Settings**, find Pages configuration, and select **GitHub Actions** in Build and deployment.
+### Install Tool
+
+First, confirm that you have installed the `dotnet sdk` version 8.0 or higher, and then proceed to install it on the command line
+
+```dotnetcli
+dotnet tool install -g Ater.EasyBlog --preview
+```
+
+After installation, you can use the `ezblog` command to operate.
 
-### Configuration
+### Using tools
 
-You can configure the basic information of the blog through `webinfo.json` in the root directory, as shown below:
+We assume that you already have some markdown documents in the `markdown` directory.
+
+Now we use the command:
+
+```pwsh
+ezblog init
+```
+
+Initialize a 'webinfo.json' file to configure the basic information of your blog. This file can be reused during subsequent generation.The document reads as follows:
 
 ```json
 {
-  "Name": "Niltor Blog", // Blog name, displayed at the top navigation of the homepage
-  "Description": " for freedom",// Description, displayed in the middle of the top of the homepage
-  "AuthorName": "Ater", // Author name, displayed in the blog list
-  "BaseHref": "/blazor-blog/", // Subdirectory
-  "Domain": "https://aterdev.github.io" // Domain name, used for generating sitemap, leave blank if not generated
+  "Name": "Niltor Blog", // blog name, displayed at the top of the homepage navigation
+  "Description": "🗽 for freedom",// description, displayed in the middle of the top of the homepage
+  "AuthorName": "Ater", // Author name, displayed in the blog list
+  "BaseHref": "/blazor-blog/", // sub directory
+  "Domain": "https://aterdev.github.io" // Domain name, used for generating a sitemap. Leave it blank if not needed
 }
 ```
 
-When you use Github Page or deploy using IIS sub-application, you need to adjust `BaseHref`. It is usually your **project name** or **subdirectory name**.
-
 > [!IMPORTANT]
-> Note that the `/` at the end of `BaseHref` is required.
+Please note that the trailing `/` in `BaseHref` is mandatory.
 >
-> If you have configured a custom domain name and are not using a subdirectory, set BaseHref to `/`.
+If you have configured a custom domain name and are not using a subdirectory, set BaseHref to '/'.
 
-After modification, commit the code, GitHub will trigger Action to automatically build.
+Then we use the command
 
-### Write a blog
+```pwsh
+ezblog build .\markdown .\WebApp
+```
 
-Please use any markdown editor you are used to write a blog, the only requirement is to put the blog content in the `Content` directory. You can create multi-level directories under this directory.
+This command will convert all markdown files in the 'markdown' directory into html files and generate them into the 'WebApp' directory.
 
-### Publish a blog
+You can use the `http-server` command to start a local server and view the generated content.
 
-You only need to commit the code normally, github action will automatically build and finally publish your blog. After the publication is successful, you can open your GitHub Page to view.
+The 'WebApp' directory contains everything you need for a static website, and you can freely deploy it wherever you need.
 
-## Deploy to other services
+## Deploy with Github Page
+
+### Fork and configure GitHub Page
+
+1. Create a new respository.
+2. Go to your own GitHub repository, click **Actions**, and enable workflows.
+3. Click **Settings**, find Pages configuration, and select **GitHub Actions** in Build and deployment.
+
+### Writing a blog
 
-If you don't use Github Page, you can also easily deploy it to other services. The core steps only require two steps.
+We assume that your md documents are all in the 'markdown' directory.
+
+Please use any markdown editor you are used to writing blogs. You can create multiple levels of directories under the 'markdown' directory to categorize md documents.
 
 ### Generate static content
 
-The `BuildSite` project is used to convert markdown to html. Please execute in the root directory:
+Use the build command, such as:
 
 ```pwsh
- dotnet run --project .\src\BuildSite\ .\Content .\WebApp Production
+ezblog build .\markdown .\_site
 ```
 
-Where `.\Content` is your markdown storage directory and `.\WebApp` is the generated static site directory.
+> [!NOTE]
+> `.\markdown` is the directory where you store md files, and you can freely modify it according to your actual situation. `.\_site` is the generated static website directory.
+
+### Publish blog
+
+Use GitHub Actions to automate the deployment of your blog site.
+
+Create a `build.yml` file in the root directory of the repository, under the `.github/workflows` directory (if it doesn't exist, create it manually). The content should be as follows:
+
+```yml
+ name: Deploy static content to Pages
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
 
-### Upload to your server
+Now you only need to push the code, and GitHub Action will automatically build and finally publish your blog. After the successful publishing, you can open your GitHub Page to view it.
 
-Copy all files in `WebApp` to your server.
+## Deploy to other services
 
-> [!TIP]
-> The `publishToLocal.ps1` script in the root directory can automatically complete the build and generate operations. The final content will be in the `WebApp` directory in the root directory.
->
-> If you use automated deployment, please refer to the scripts in .github/workflows.
+If you don't use Github Page, you can easily deploy to other services as well. The core steps only require two steps.
 
-## Update
+### Generate static website
 
-The upstream code update is based on the `dev` branch. You can merge the `dev` branch into your `dev` branch to get the latest code updates.
+We assume that your documents are all located in the 'markdown' directory.
+First, use the 'ezblog init' command to generate the 'webinfo. json' configuration file, and modify it according to actual needs.
+Then execute 'ezblog build'/ The markdown./wwroot ` command.
 
-`main` is the default branch for building and publishing. Please do not merge it into your `main` branch.
+### Upload to your server
 
-It is recommended to use `dev` or your own branch to write blogs and customize content, and then merge it to the `main` branch to trigger automatic build.
+Copy all files from 'wwwroot' to your server.
 
 ## Custom Develop
 

diff --git a/README_cn.md b/README_cn.md
@@ -1,37 +1,53 @@
-# Blog
+# EasyBlog
 
 📘[Englisth](./README.md)   📘[中文](./README-cn.md)
 
-本博客系统通过构建工具生成`纯静态`的博客网站，借助`GitHub Pages`，你可以在5分钟内免费拥有个人博客。 它具有以下特点
+本工具通过命令将`markdown`文档生成`纯静态`的博客网站，借助`GitHub Pages`，你可以在5分钟内免费拥有个人博客。 它具有以下特点
 
+- 提供命令行工具生成静态网站
 - 生成纯静态网站，访问速度极快
-- 使用markdown格式来编写博客内容
-- 基于git代码管理来存储你的博客
-- 使用CI工具来自动化部署你的博客站点
+- 支持markdown格式编写的内容
+- 支持搜索、分类、存档筛选
+- 自定义网站名称和说明等
 
 效果展示：[NilTor's Blog](https://blog.dusi.dev/)
 
 ## 🎖️功能
 
 - 主页博客列表，支持搜索和分类和存档筛选
 - 自定义网站名称和说明
+- 支持文档中本地图片路径
 - 随系统变化的Light和Dark主题
 - 移动端的自适应显示
 - TOC支持
 - mermaid,nomnoml,Math的渲染支持
 - 代码高亮及复制支持
 
-## 使用Github Page部署
+## 🚀快速开始
 
-### Fork并配置GitHub Page
+目前工具已经以`dotnet tool`的形式发布。你可以很方便的安装并使用。
 
-1. 点击`Fork`按钮，并创建自己的仓库。 并取消选择 Copy the main branch only。
-2. 进入自己的GitHub仓库，点击`Actions`，启用workflows。
-3. 点击`Settings`，找到Pages配置，在Build and deployment 选项中选择`GitHub Actions`.
+### 安装工具
+
+首先确认你们已经安装了`dotnet sdk`8.0或以上版本，然后在命令行中安装:
+
+```dotnetcli
+dotnet tool install -g Ater.EasyBlog --preview
+```
 
-### 配置
+安装完成后，你可以使用`ezblog`命令来操作。
 
-你可以通过根目录下的`webinfo.json`，对博客基础信息进行配置，如下所示：
+### 使用工具
+
+我们假设，你已经有一些markdown文档，它在`markdown`目录下。
+
+现在我们使用命令:
+
+```pwsh
+ezblog init
+```
+
+初始化一个`webinfo.json`文件，用来配置你的博客基本信息，该文件在后续生成时可重复使用。该文件内容如下:
 
 ```json
 {
@@ -43,53 +59,111 @@
 }
 ```
 
-当你使用Github Page或使用IIS子应用部署时，需要调整`BaseHref`。通常是你的**项目名称**或**子目录名**。
-
 > [!IMPORTANT]
 > 注意，`BaseHref`尾部的`/`是必需的。
 >
 > 如果你配置了自定义域名，并且没有使用子目录，请将BaseHref设置为`/`。
 
-修改后提交代码，GitHub会触发Action自动构建。
+然后我们使用命令
 
-### 编写博客
+```pwsh
+ezblog build .\markdown .\WebApp
+```
 
-请使用任何你习惯的markdown编辑器编写博客,唯一的要求是将博客内容放到`Content`目录下。你可以在该目录下创建多级目录。
+该命令将会把`markdown`目录下的所有markdown文件转换成html文件，并生成到`WebApp`目录下。
 
-### 发布博客
+你可以使用`http-server`命令来启动一个本地服务器，查看生成的内容。
 
-你只需要正常提交代码即可，github action会自动构建并最终发布你的博客，发布成功后可打开您的 GitHub Page 查看。
+`WebApp`目录下就是静态网站需要的一切，你可以将它自由的部署到你需要的地方。
 
-## 部署到其他服务
+## 使用Github Page部署
 
-如果你不使用Github Page，那么你也可以轻松的部署到其他服务。核心的步骤只需要两步。
+### 配置GitHub Page
+
+1. 在Github上创建自己的仓库。
+2. 进入自己的GitHub仓库，点击`Actions`，启用workflows。
+3. 点击`Settings`，找到Pages配置，在Build and deployment 选项中选择`GitHub Actions`.
+
+当你使用Github Page或使用IIS子应用部署时，需要调整`webinfo.json`中的`BaseHref`。通常是你的**项目名称**或**子目录名**。
+
+### 编写博客
+
+我们假设你的md文档都在`markdown`目录下。
+
+请使用任何你习惯的markdown编辑器编写博客，你可以在`markdown`目录下创建多级目录，以对md文档进行分类。
 
 ### 生成静态内容
 
-`BuildSite`项目是用来将markdown转换成html的，请在根目录执行:
+使用build命令，如：
 
 ```pwsh
- dotnet run --project .\src\BuildSite\ .\Content .\WebApp Production
+ezblog build .\markdown .\_site
 ```
 
-其中`.\Content`是你的markdown存储目录，`.\WebApp`是生成的静态站点目录。
+> [!NOTE]
+> `.\markdown`是你存放md文件的目录，可根据实际情况自由修改。`.\_site`是生成后的静态网站目录。
 
-### 上传到你的服务器
+### 发布博客
 
-将`WebApp`中的所有文件复制到你的服务器即可。
+使用`GitHub Action`来自动化部署你的博客站点。
+
+在仓库的根目录`.github/workflows`目录(没有则手动创建)下创建`build.yml`文件，内容如下：
+
+```yml
+name: Deploy static content to Pages
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
 
-> [!TIP]
-> 根目录下的`publishToLocal.ps1`脚本可以自动完成构建和生成的操作，最终内容将在根目录下`WebApp`目录中。
->
-> 如果你使用自动化部署，可参考.github/workflows中的脚本。
+现在只需要推送代码即可，`GitHub Action`会自动构建并最终发布你的博客，发布成功后可打开您的 GitHub Page 查看。
+
+## 部署到其他服务
 
-## 更新
+如果你不使用Github Page，那么你也可以轻松的部署到其他服务。核心的步骤只需要两步。
+
+### 生成静态网站
+
+我们假设你的文档都位于`markdown`目录下。
 
-上游代码的更新以`dev`分支为准，你可以将`dev`分支合并到你的`dev`分支，以获取最新的代码更新。
+先使用`ezblog init`命令生成`webinfo.json`配置文件，并根据实际需求修改。
 
-`main`作为默认的构建发布的分支，请不要合并到你的`main`分支。
+然后执行`ezblog build ./markdown ./wwwroot`命令。
+
+### 上传到你的服务器
 
-建议您使用`dev`或其他自己的分支来编写博客和自定义内容，然后再合并到`main`分支以触发自动构建。
+将`wwwroot`中的所有文件复制到你的服务器即可。
 
 ## 二次开发