From 4c9f2090420a7ad6c7e6b44c66e45f3bfe600a54 Mon Sep 17 00:00:00 2001 From: ClovertaTheTrilobita Date: Thu, 26 Mar 2026 14:23:09 +0200 Subject: [PATCH] update doc --- README-en.md | 64 +++++++++++++++++++++++++++ README.md | 1 + docs/EnvVariables-en.md | 45 +++++++++++++++++++ docs/EnvVariables.md | 2 + docs/GithubActions-en.md | 96 ++++++++++++++++++++++++++++++++++++++++ docs/GithubActions.md | 2 + 6 files changed, 210 insertions(+) create mode 100644 README-en.md create mode 100644 docs/EnvVariables-en.md create mode 100644 docs/GithubActions-en.md diff --git a/README-en.md b/README-en.md new file mode 100644 index 0000000..e971468 --- /dev/null +++ b/README-en.md @@ -0,0 +1,64 @@ +# SanYeCao-Blog +

[中文 | English]

+


+ ✨SanYeCao Blog✨
+ 🌊Lightweight / Fast / Beautiful🌊

+ Built With
+ Static Badge + Static Badge + Static Badge +
+

+ +## 😋 Features + +
+ +image + +
+ +- Built with purely static pages, responsive, lightweight, and visually pleasing +- Easy to use, with automatic deployment via GitHub Actions +- Astro Is All You Need + +For more previews, please see: [Images.md](docs/Images.md). + +## 🧳 Usage + +### 1. Fork this repository + +image + +Then clone it to your local machine. + +### 2. Run / Build + +> [!IMPORTANT] +> +> Before getting started, please rename `.env.example` in the root directory to `.env` and configure the environment variables, otherwise some features may not work properly. + +For details about environment variables, see: [EnvVariables.md](docs/EnvVariables.md) + +- Local development + + ```shell + npm run dev + ``` + +- Local build + + ```shell + npm run build + ``` + +### 3. Deployment + +#### Deploy automatically with GitHub Actions + +For details, see: [GithubActions.md](docs/GithubActions.md). + +#### Manual deployment + +Upload the generated `dist/` directory to your server, and configure `NGINX` to point to `index.html`. + diff --git a/README.md b/README.md index 36ee0a3..0483953 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # SanYeCao-Blog +

[中文 | English]


✨三叶草Blog✨
🌊轻度/快速/美观🌊

diff --git a/docs/EnvVariables-en.md b/docs/EnvVariables-en.md new file mode 100644 index 0000000..c8c427d --- /dev/null +++ b/docs/EnvVariables-en.md @@ -0,0 +1,45 @@ +## Environment Variables + +

[中文 | English]

+ +The following environment variables are listed in the project's `.env.example` file: + +| Variable Name | Description | +| --------------------- | ----------- | +| `GITHUB_TOKEN` | Enter your [Personal access token](https://github.com/settings/personal-access-tokens) | +| `GISCUS_REPO_OWNER` | Your GitHub username, for example `ClovertaTheTrilobita` | +| `GISCUS_REPO_NAME` | Your code repository name, for example `SanYeCao-blog` | +| `GISCUS_CATEGORY_ID` | The category ID of `GISCUS`, see the explanation below | +| `GISCUS_DATA_REPO_ID` | The repository ID of `GISCUS`, see the explanation below | + +### 1. `GITHUB_TOKEN` + +It can greatly increase your GitHub API rate limit. Open this link: [Personal access tokens](https://github.com/settings/personal-access-tokens) + +Choose `Generate new token`. + +Then copy the generated token into the corresponding place in your `.env` file. + +### 2. `GISCUS` + +This blog uses a comment section based on the `GISCUS API`, which can map part of the GitHub repository's Discussions section onto your webpage as a comment area. + +#### ① Enable Discussions in your repository + +Go to `Settings > General > Features` in your repository and check `Discussions` to enable it. + +Then go to the `Discussions` page, click the pencil icon next to `Categories` on the left side of the page, and then click `New category` to create a new category named `Comments`. + +#### ② Install the Giscus GitHub App + +Open this link: [GitHub App - giscus](https://github.com/apps/giscus) + +Install it into the blog code repository you forked. + +Then go to: [giscus.app](https://giscus.app) + +In the `Repository` field, enter your repository address, and in `Page ↔️ Discussions Mapping`, choose `Discussion title contains a specific term`. + +In `Discussion Category`, select the `Comments` category you just created. + +Finally, in the generated code below, find `data-category-id` and `data-repo-id`, and fill them into the environment variables. \ No newline at end of file diff --git a/docs/EnvVariables.md b/docs/EnvVariables.md index 32cc253..bccacb8 100644 --- a/docs/EnvVariables.md +++ b/docs/EnvVariables.md @@ -1,5 +1,7 @@ ## 环境变量说明 +

[中文 | English]

+ 在项目的`.env.example`中，列举了如下环境变量 | 变量名 | 内容 | diff --git a/docs/GithubActions-en.md b/docs/GithubActions-en.md new file mode 100644 index 0000000..e060048 --- /dev/null +++ b/docs/GithubActions-en.md @@ -0,0 +1,96 @@ +## Automatic Deployment with GitHub Actions + +

[中文 | English]

+ +> [!NOTE] +> +> This project's GitHub Actions workflow listens for `git push` operations in the `src/blog` and `src/friends` directories. If either directory is updated, the build pipeline will be triggered. + +> [!IMPORTANT] +> +> To use this feature, you need to fork this project into your own repository. The workflow can only run in your own repository. + +### 1. Set up SSH keys + +In your repository, go to `Settings > Secrets and variables > Actions`, and add three `Repository secrets`: + +| Secret Name | Purpose | +| -------------------- | ------------------------------------------------ | +| `DEPLOY_KNOWN_HOSTS` | Allows GitHub CI to recognize the target server | +| `DEPLOY_SSH_KEY` | Used to log in to the target server | +| `ENV_FILE` | Private environment variables | + +#### 1. `DEPLOY_KNOWN_HOSTS` + +Run the following command in your terminal: + +```shell +ssh-keyscan -H +```` + +Then copy all generated output into this environment variable. + +#### 2. `DEPLOY_SSH_KEY` + +It is recommended to generate a dedicated SSH key specifically for GitHub deployment. + +Run this command on your local machine or server terminal: + +```shell +ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/github_actions_deploy +``` + +After running it, you will get two files: + +```shell +~/.ssh/github_actions_deploy +~/.ssh/github_actions_deploy.pub +``` + +> **`github_actions_deploy`** → private key, put this into `DEPLOY_SSH_KEY` +> +> **`github_actions_deploy.pub`** → public key, add this to your server + +##### ① Set the GitHub private key + +View the private key content: + +```shell +cat ~/.ssh/github_actions_deploy +``` + +Copy the full output into the variable value. + +##### ② Set the server public key + +Then log in to your server terminal and add the contents of `~/.ssh/github_actions_deploy.pub` to the server's `~/.ssh/authorized_keys`, so that GitHub CI can access the server. + +#### 3. `ENV_FILE` + +This variable is used to generate the `.env` file required for building. + +If you have already configured your `.env`, it should contain the following: + +```env +GITHUB_TOKEN= +GISCUS_REPO_OWNER= +GISCUS_REPO_NAME= +GISCUS_CATEGORY_ID= +GISCUS_DATA_REPO_ID= +``` + +If you have not configured these yet or do not know what they mean, please see: [EnvVariables-en.md](EnvVariables-en.md) + +Simply copy all contents of your `.env` file into the variable value. + +### 2. Set up repository variables + +Also in `Settings > Secrets and variables > Actions`, add four `Repository variables`: + +| Variable Name | Value Example | +| ------------- | --------------------------------------------------------------------------- | +| `DEPLOY_HOST` | Server IP address, for example `192.168.1.1` | +| `DEPLOY_PATH` | Deployment path on the server, for example `/www/wwwroot/blog.cloverta.top` | +| `DEPLOY_PORT` | SSH port of the server, usually `22` | +| `DEPLOY_USER` | Login username, for example `root` | + diff --git a/docs/GithubActions.md b/docs/GithubActions.md index 4703038..7ff23ee 100644 --- a/docs/GithubActions.md +++ b/docs/GithubActions.md @@ -1,5 +1,7 @@ ## Github Actions自动部署 +

[中文 | English]

+ > [!NOTE] > > 此项目的Github Actions监听`src/blog`和`src/friends`两个目录的`git push`操作，两个目录有更新则触发构建流水线。