📘Englisth 📘中文

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

• 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/

• Blog list on the homepage, supporting search, category and archive filtering
• Customize website name and description
• Light and Dark themes that change with the system
• Adaptive display for mobile devices
• TOC support
• mermaid, nomnoml, Math rendering support
• Code highlighting and copy support

Currently, the tool has been released in the form of 'dotnet tool'.You can easily install and use it.

First, confirm that you have installed the dotnet sdk version 8.0 or higher, and then proceed to install it on the command line

dotnet tool install -g Ater.EasyBlog --preview

After installation, you can use the ezblog command to operate.

We assume that you already have some markdown documents in the markdown directory.

Now we use the command:

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:

{
  "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
}

If you have configured a custom domain name and are not using a subdirectory, set BaseHref to '/'.

Then we use the command

ezblog build .\markdown .\WebApp

This command will convert all markdown files in the 'markdown' directory into html files and generate them into the 'WebApp' directory.

You can use the http-server command to start a local server and view the generated content.

The 'WebApp' directory contains everything you need for a static website, and you can freely deploy it wherever you need.

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.

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.

Use the build command, such as:

ezblog build .\markdown .\_site

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:

 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

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.

If you don't use Github Page, you can easily deploy to other services as well. The core steps only require two steps.

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.

Copy all files from 'wwwroot' to your server.

After forking, you will have all the custom permissions, because all the source codes are already in your own repository.

The core project is BuildSite, which is used to generate static files, including converting markdown files to html files.

The BuildSite project is a .NET project. You need to install .NET SDK 8.0.

Additionally, you can install (optional):

• http-server: To start local static content for debugging.
• tailwindcss: To generate CSS style content.
• typescript: To use the tsc command.

1. Preview the project:
   1. Open the terminal, execute http-server in the WebApp directory, and then open http:https://127.0.0.1:8080 in your browser.
2. Generate static content:
   1. Execute dotnet run --project ./src/BuildSite ./Content ./WebApp in the root directory to generate the latest static content.
   2. Alternatively, run the build.ps1 script in the root directory.
3. Refresh the browser to see the latest generated content.

The homepage content template is located at src\BuildSite\template\index.html.tpl. It includes the following variables:

You can modify the layout and style of the homepage according to your own ideas.

The homepage content includes the search and category filtering functions of the blog. The functional code is in WebApp\js\index.js.

For customizing the blog list and category list, you can refer to the GenBlogListHtml and GenSiderBar methods in the HtmlBuilder.cs file in the BuildSite project.

We will provide more flexible customization methods in the future.

The blog post content template is located at src\BuildSite\template\blog.html.tpl. It includes the following variables:

You can modify the style of the blog post page through WebApp/css/markdown.css and define the logic through WebApp/js/markdown.js.

This project uses ColorCode to format the code content in markdown. ColorCode uses regular expressions to match the code content. If you need to define code highlighting, you need to:

1. Add or modify regular expression rules. You can find the corresponding language definition in the ColorCode.Core/Compilation/Languages directory. If it does not exist, you can add new language support.
2. If it is a newly added language, you need to load it in ColorCode.Core/Languages.cs.