mirror of
https://github.com/ClovertaTheTrilobita/SanYeCao-blog.git
synced 2026-04-01 17:50:13 +00:00
update doc
This commit is contained in:
parent
d1b1dd96ce
commit
4c9f209042
6 changed files with 210 additions and 0 deletions
64
README-en.md
Normal file
64
README-en.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# SanYeCao-Blog
|
||||
<p align="right">[<a href="README.md">中文</a> | <a href="README-en.md">English</a>]</p>
|
||||
<p align="center"><br>
|
||||
✨SanYeCao Blog✨<br>
|
||||
🌊Lightweight / Fast / Beautiful🌊<br><br>
|
||||
Built With<br>
|
||||
<img alt="Static Badge" src="https://img.shields.io/badge/Astro-6.0-purple">
|
||||
<img alt="Static Badge" src="https://img.shields.io/badge/Nodejs-24-green">
|
||||
<img alt="Static Badge" src="https://img.shields.io/badge/Heart-♥️-pink">
|
||||
<br>
|
||||
</p>
|
||||
|
||||
## 😋 Features
|
||||
|
||||
<br>
|
||||
|
||||
<img width="2879" height="1853" alt="image" src="https://github.com/user-attachments/assets/9f6f7018-c8a4-46f7-9d30-1132fcea53da" style="zoom:25%;" />
|
||||
|
||||
<br>
|
||||
|
||||
- Built with purely static pages, responsive, lightweight, and visually pleasing
|
||||
- Easy to use, with automatic deployment via GitHub Actions
|
||||
- <del><i>Astro Is All You Need</i></del>
|
||||
|
||||
For more previews, please see: <b>[Images.md](docs/Images.md)</b>.
|
||||
|
||||
## 🧳 Usage
|
||||
|
||||
### 1. Fork this repository
|
||||
|
||||
<img width="294" height="155" alt="image" src="https://github.com/user-attachments/assets/6ffc9a32-c084-463f-8988-f7488baa44e0" />
|
||||
|
||||
Then clone it to your local machine.
|
||||
|
||||
### 2. Run / Build
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> Before getting started, please <b>rename `.env.example` in the root directory to `.env` and configure the environment variables</b>, otherwise some features may not work properly.
|
||||
|
||||
For details about environment variables, see: <b>[EnvVariables.md](docs/EnvVariables.md)</b>
|
||||
|
||||
- Local development
|
||||
|
||||
```shell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
- Local build
|
||||
|
||||
```shell
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 3. Deployment
|
||||
|
||||
#### Deploy automatically with GitHub Actions
|
||||
|
||||
For details, see: <b>[GithubActions.md](docs/GithubActions.md)</b>.
|
||||
|
||||
#### Manual deployment
|
||||
|
||||
Upload the generated `dist/` directory to your server, and configure `NGINX` to point to `index.html`.
|
||||
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
# SanYeCao-Blog
|
||||
|
||||
<p align="right">[<a href="README.md">中文</a> | <a href="README-en.md">English</a>]</p>
|
||||
<p align="center"><br>
|
||||
✨三叶草Blog✨<br>
|
||||
🌊轻度/快速/美观🌊<br><br>
|
||||
|
|
|
|||
45
docs/EnvVariables-en.md
Normal file
45
docs/EnvVariables-en.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
## Environment Variables
|
||||
|
||||
<p align="right">[<a href="EnvVariables.md">中文</a> | <a href="EnvVariables-en.md">English</a>]</p>
|
||||
|
||||
The following environment variables are listed in the project's `.env.example` file:
|
||||
|
||||
| Variable Name | Description |
|
||||
| --------------------- | ----------- |
|
||||
| `GITHUB_TOKEN` | Enter your <b>[Personal access token](https://github.com/settings/personal-access-tokens)</b> |
|
||||
| `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: <b>[Personal access tokens](https://github.com/settings/personal-access-tokens)</b>
|
||||
|
||||
Choose <b>`Generate new token`</b>.
|
||||
|
||||
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 <b>`Settings > General > Features`</b> in your repository and check <b>`Discussions`</b> to enable it.
|
||||
|
||||
Then go to the <b>`Discussions`</b> page, click the pencil icon next to <b>`Categories`</b> on the left side of the page, and then click <b>`New category`</b> to create a new category named <b>`Comments`</b>.
|
||||
|
||||
#### ② Install the Giscus GitHub App
|
||||
|
||||
Open this link: <b>[GitHub App - giscus](https://github.com/apps/giscus)</b>
|
||||
|
||||
Install it into the blog code repository you forked.
|
||||
|
||||
Then go to: <b>[giscus.app](https://giscus.app)</b>
|
||||
|
||||
In the <b>`Repository`</b> field, enter your repository address, and in <b>`Page ↔️ Discussions Mapping`</b>, choose <b>`Discussion title contains a specific term`</b>.
|
||||
|
||||
In <b>`Discussion Category`</b>, select the <b>`Comments`</b> category you just created.
|
||||
|
||||
Finally, in the generated code below, find <b>`data-category-id`</b> and <b>`data-repo-id`</b>, and fill them into the environment variables.
|
||||
|
|
@ -1,5 +1,7 @@
|
|||
## 环境变量说明
|
||||
|
||||
<p align="right">[<a href="EnvVariables.md">中文</a> | <a href="EnvVariables-en.md">English</a>]</p>
|
||||
|
||||
在项目的`.env.example`中，列举了如下环境变量
|
||||
|
||||
| 变量名 | 内容 |
|
||||
|
|
|
|||
96
docs/GithubActions-en.md
Normal file
96
docs/GithubActions-en.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
## Automatic Deployment with GitHub Actions
|
||||
|
||||
<p align="right">[<a href="GithubActions.md">中文</a> | <a href="GithubActions-en.md">English</a>]</p>
|
||||
|
||||
> [!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 <b>`Settings > Secrets and variables > Actions`</b>, 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 <your-server-ip>
|
||||
````
|
||||
|
||||
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: <b>[EnvVariables-en.md](EnvVariables-en.md)</b>
|
||||
|
||||
Simply copy all contents of your `.env` file into the variable value.
|
||||
|
||||
### 2. Set up repository variables
|
||||
|
||||
Also in <b>`Settings > Secrets and variables > Actions`</b>, 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` |
|
||||
|
||||
|
|
@ -1,5 +1,7 @@
|
|||
## Github Actions自动部署
|
||||
|
||||
<p align="right">[<a href="GithubActions.md">中文</a> | <a href="GithubActions-en.md">English</a>]</p>
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> 此项目的Github Actions监听`src/blog`和`src/friends`两个目录的`git push`操作，两个目录有更新则触发构建流水线。
|
||||
|
|
|
|||
Loading…
Reference in a new issue