Skip to content

Latest commit

 

History

History
262 lines (191 loc) · 9.5 KB

README_zh.md

File metadata and controls

262 lines (191 loc) · 9.5 KB
Raw

Aki-SSG

又一个基于 Next.js 的静态站点生成器

简介

Aki-SSG 是一个静态网站生成器，它将您的 Markdown 内容转换为基于 Next.js 的网站，使用 Tailwind CSS 作为 CSS 框架。

快速上手

  1. 将这个项目 fork 到你自己的仓库。
  2. 将其 clone 到本地。
  3. 将站点相关信息写入 src/data/site-config.ts。
  4. 运行 pnpm install 以安装依赖。
  5. 编写站点上的内容与页面。
  6. 运行 pnpm dev 以预览站点。
  7. 运行 pnpm build 以构建站点。
  8. 将 out/ 目录中的文件上传到您的 Web 服务器中。
  9. 为 Nginx 配置 Rewrite 规则。
  10. 享用您的站点！

Rewrite 规则

您应该将以下内容添加到您的虚拟主机配置文件中。

（目前只提供 Nginx 配置文件范例）

location / {
	try_files $uri $uri.html $uri/ =404;
}
error_page 404 /404.html;
location = /404.html {
	internal;
}

Site Config

站点的配置信息将储存在 src/data/site-config.ts 文件中，该文件有类型标注，因此会有类型提示。

可用的配置如下：

import { createConfig } from "../utils/createConfig";

export const config: SiteConfig = createConfig({
		author: {
			name: "Test", // 作者名，在页脚、版权信息展示。
			email: "[email protected]", // 作者邮箱，用于获取在导航栏展示的头像。
		},
		blog: {
			hostname: "example.com", // 网站域名
			title: "Aki-SSG", // 网站标题
			description: "Yet another site generated by Aki-SSG", // 网站描述，在 Header 展示
			favicon: "/favicon.ico", // 网站 Favicon
		},
		style: {
			primary_color: "#6db0ec", // 网站主题色
			header_image: "https://blog-oss.allenyou.top/image/658ad4c208349.png", // 网站 Header 图像
			header_image: { // 也可以用这种方法为深色模式和浅色模式分别配置不同的图像
				default: "https://blog-oss.allenyou.top/image/658ad4c208349.png", // 浅色模式
				dark: "https://blog-oss.allenyou.top/image/658ad4c208349.png", // 深色模式
			},
		},
		comment: { // 评论配置
			enabled: false, // 禁用评论功能
		},
		comment: { // 如下设置启用 Waline 评论
			enabled: true,
			waline_api: ""
		},
		optimize: { // 优化配置
			gravatar_mirror: "https://gravatar.com/avatar/", // Gravatar 镜像源
			cdn_prefix: "", // 可选，加载静态资源时使用的 CDN 地址前缀（参见 next.config.ts 文件中的 assetPrefix 配置项）
							// 如果该项没有配置，静态资源将全部从本地加载。
			thumb_query: "", // 可选，代表文章中引用图片的缩略图 URL 末尾的部分。
							// 当文章中图片没有完全加载时，将显示缩略图代替。
							// 如果该项没有配置，将不显示缩略图。
		}

		gravatar_mirror: "https://gravatar.com/avatar/",
	};);

页面与文章

页面和文章将使用 Aki-SSG 风格的 Markdown 编写，并保存为 .md 文件。一些信息可以在文件的头部信息部分（主体之前用---引用的部分，采用 YAML 格式编写）中进行描述。

页面

页面应保存为 .md 文件，并放置在 src/data/pages/ 目录中。每个文件对应一个页面。

文件应如下所示：

---
slug: example
title: "示例页面"
enable_comment: false
allow_index: true
navigation_title: "页面"
navigation_index: 1
---

页面的内容应在此处使用 Markdown 编写。

文件头部信息（YAML 格式）中的属性应如下所示：

属性名称 描述
slug 表示页面的 URL。例如，如果设置为example，则此页面的 URL 将为/example。
title 表示页面的标题。
enable_comment（可选） 一个布尔值，表示是否在此页面上启用评论功能。默认值为false。
allow_index（可选） 一个布尔值，表示是否在robots.txt中允许搜索引擎爬虫索引此页面。默认值为false。
navigation_title（可选） 表示导航栏上直接指向此页面的链接内容。如果留空，则此页面将不会出现在导航栏上。
navigation_index（可选） 一个整数，表示此页面在导航栏中出现的顺序（按升序排列）。默认值为0。

文章

文章应保存为 .md 文件，存放在 src/data/posts/ 目录下。每个文件对应一篇文章。

文件内容应如下所示：

---
id: 1
title: "Hello, World!"
description: "这是一篇测试文章"
modified_at: "2024-10-04"
---

正文应在此处使用 Markdown 编写。

文件头部信息（YAML 格式）中的属性应如下所示：

属性名称 描述
id 一个唯一的整数，用于标识这篇文章。文章的 URL 将会是/posts/:id。
title 文章的标题。
modified_at 文章最后一次被修改的日期和时间。
description(可选) 文章的摘要。如果留空，则默认使用“没有描述”作为摘要内容。

友情链接

友情链接将被保存在 src/data/friend-link.ts 文件中。该文件有类型标注，因此会有类型提示。

文件内容将如下所示：

export const friend_link_list: FriendLink[] = [
	{
		// 友情链接的名称
		title: "示例友情链接",
		// 友情链接的URL
		url: "https://example.com",
		// 友情链接的描述
		description: "这是一个示例友情链接。",
		// 友情链接的头像图片（可选）
		// 如果未设置，则默认使用默认头像。
		avatar: "",
	},
];

Aki-SSG Flavored Markdown

Aki-SSG 使用基于 unified的扩展 Markdown 语法。

除了标准 Markdown 的语法，您还可以使用如下语法：

GitHub Alerts

Aki-SSG 支持 GitHub 风格的提示。

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

GitHub Flavored Markdown

Aki-SSG Flavored Markdown 完全支持 GFM 语法。

LaTex

Aki-SSG 使用 MathJax 渲染 LaTex 公式。

使用 $ 公式 $ 插入行内公式，或使用如下语法插入块公式。

$$
公式
$$

指令

Aki-SSG 支持通用指令/插件语法扩展。以下是可用的指令：

Bilibili 视频

使用 ::bilibili[bvid="" cid=""] 来嵌入 Bilibili 视频播放器。

参数 描述
bvid 要嵌入的视频的 BV ID。
cid（可选） 要嵌入的视频的分 P ID。

友情链接

使用 ::friend_links 来插入友情链接列表。

友情链接将从 src/data/friend-link.ts 文件中加载。

对话

每个对话应该由 :::chat 与 ::: 包裹。

在对话内，可以使用 ::chat_sender{name="Name" avatar="Avatar URL" self} 定义一位对话参与者，参数如下：

参数 描述
name 参与者显示的名称
avatar（可选） 参与者显示的头像图片的 URL。如果未指定，将取参与者名称第一个字符 + 背景颜色为头像。
self（可选） 若带有该参数，则该参与者的发言将全部显示在右边。

如果重复定义对话参与者，后定义的将覆盖先定义的。

使用 ::chat_item[Text]{name="Name" avatar="Avatar URL" self} 添加一句对话，参数如下：

参数 描述
name 参与者显示的名称，若该参与者已经用 ::chat_sender 定义过将直接使用该参与者相关信息。
avatar（可选） 参与者显示的头像图片的 URL。如果未指定，将取参与者名称第一个字符 + 背景颜色为头像。
self（可选） 若带有该参数，则该参与者的发言将全部显示在右边。

需要注意的是，::chat_sender 定义的参与者具有最高优先级，在冲突时将覆盖 ::chat_item 参数中设定的信息。

其他

RSS Feed 文件将保存在 /feed.xml。
Sitemap 文件将保存在 /sitemap.xml。
robots.txt 文件将保存在 /robots.txt。

鸣谢

本项目的样式设计模仿自 tcdw/koi。感谢 @tcdw！