docs: add basic documentation for theme development (#102)

添加最基本的主题开发文档，仅编写从创建主题项目到最终预览的部分。 /kind documentation ```release-noe None ```
2 years ago · f92e5ca387
parent 987a9c9d3f
commit f92e5ca387
3 changed files with 134 additions and 3 deletions
--- a/docs/developer-guide/theme/prepare.md
+++ b/docs/developer-guide/theme/prepare.md
@ -1,6 +1,103 @@
 ---
 title: 准备工作
-description: 主题开发的环境搭建
+description: 主题开发所需的准备工作和基本的项目搭建
 ---

-WIP
+此文档将讲解 Halo 2.0 主题开发的基本流程，从创建主题项目到最终预览主题效果。
+
+## 搭建开发环境
+
+Halo 在本地开发环境的运行可参考[开发环境运行](../core/run.md)，或者使用 [Docker](../../getting-started/install/docker.md) 运行。
+
+## 新建一个主题
+
+Halo 的主题存放于工作目录的 `themes` 目录下，即 `~/halo-next/themes`，在该目录下新建一个文件夹，例如 `theme-foo`。当前一个最小可被系统加载的主题必须在主题根目录下包含 `theme.yaml` 配置文件。
+
+以 [theme-default](https://github.com/halo-sigs/theme-default) 为例：
+
+```yaml title="theme.yaml"
+apiVersion: theme.halo.run/v1alpha1
+kind: Theme
+metadata:
+  name: theme-default
+spec:
+  displayName: Default
+  author:
+    name: halo-dev
+    website: https://halo.run
+  description: Default theme for Halo 2.0
+  logo: https://halo.run/logo
+  website: https://github.com/halo-sigs/theme-default
+  repo: https://github.com/halo-sigs/theme-default.git
+  settingName: "theme-default-setting"
+  configMapName: "theme-default-configMap"
+  version: 1.0.0
+  require: 2.0.0
+```
+
+| 字段                  | 描述                                                        | 是否必填 |
+| --------------------- | ----------------------------------------------------------- | -------- |
+| `metadata.name`       | 主题的唯一标识                                              | 是       |
+| `spec.displayName`    | 显示名称                                                    | 是       |
+| `spec.author.name`    | 作者名称                                                    | 否       |
+| `spec.author.website` | 作者网站                                                    | 否       |
+| `spec.description`    | 主题描述                                                    | 否       |
+| `spec.logo`           | 主题 Logo                                                   | 否       |
+| `spec.website`        | 主题网站                                                    | 否       |
+| `spec.repo`           | 主题托管地址                                                | 否       |
+| `spec.settingName`    | 设置表单定义的名称，需要同时创建对应的 `settings.yaml` 文件 | 否       |
+| `spec.configMapName`  | 设置持久化的 ConfigMap 名称                                 | 否       |
+| `spec.version`        | 主题版本                                                    | 是       |
+| `spec.require`        | 所需 Halo 的运行版本                                        | 是       |
+
+:::info 提示
+关于主题项目的目录结构请参考[主题目录结构](./structure.md)。
+:::
+
+## 通过模板创建
+
+目前 Halo 为了让开发者能够尽快搭建主题项目，提供了一些初始模板，开发者可以根据实际需要选择使用。
+
+- [halo-sigs/theme-starter](https://github.com/halo-dev/theme-starter) - 最基础的主题模板，包含了主题的基本目录结构。
+- [halo-sigs/theme-vite-starter](https://github.com/halo-dev/theme-vite-starter) - 与 Vite 集成的主题模板，由 Vite 负责资源构建。
+- [halo-sigs/theme-modern-starter](https://github.com/halo-dev/theme-modern-starter) - 集成了现代前端技术栈的 Halo 2.0 的主题开发模板。
+- [halo-sigs/theme-astro-starter](https://github.com/halo-sigs/theme-astro-starter) - 与 Astro 集成的主题模板，使用 Astro 对模板进行预编译。
+
+:::info 提示
+以上 GitHub 都被设置为了模板仓库（Template repository），点击仓库主页的 `Use this template` 按钮即可通过此模板创建一个新的仓库。
+:::
+
+## 创建第一个页面模板
+
+Halo 使用 [Thymeleaf](https://www.thymeleaf.org/) 作为后端模板引擎，后缀为 `.html`，与单纯编写 HTMl 一致。在 Halo 的主题中，主题的模板文件存放于 `templates` 目录下，例如 `~/halo-next/themes/theme-foo/templates`。为了此文档方便演示，我们先在 `templates` 创建一个首页的模板文件 `index.html`：
+
+```html title="templates/index.html"
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title th:text="${site.title}"></title>
+  </head>
+  <body>
+    <h1>Hello World!</h1>
+    <ul>
+      <li th:each="post : ${posts.items}">
+        <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
+      </li>
+    </ul>
+  </body>
+</html>
+```
+
+## 安装主题
+
+目前我们已经创建好了主题的项目，但并不会直接被 Halo 识别和加载，请按照以下的步骤安装和启用主题：
+
+1. 访问 Console 管理界面，进入主题管理页面。
+2. 点击右上角 `切换主题` 按钮，在选择主题弹窗中切换到 `未安装` 页面。
+3. 找到我们刚刚创建的主题，点击安装即可。
+4. 选择刚刚安装的主题，点击右上角的 `启用` 按钮。
+
+此时 Halo 就已经成功加载并使用了该主题。然后我们访问首页 [http://localhost:8090](http://localhost:8090) 就可以看到我们刚刚编写的 `index.html` 模板渲染后的页面了。
--- a/docs/developer-guide/theme/structure.md
+++ b/docs/developer-guide/theme/structure.md
@ -0,0 +1,33 @@
+---
+title: 目录结构
+description: 主题的目录结构介绍
+---
+
+Halo 2.0 的主题基本目录结构如下：
+
+```bash title="~/halo-next/themes/my-theme"
+my-theme
+├── templates/
+│   ├── assets/
+│   │   ├── css/
+│   │   │   └── style.css
+│   │   └── js/
+│   │       └── main.js
+│   ├── index.html
+│   ├── post.html
+│   ├── page.html
+│   ├── tag.html
+│   ├── tags.html
+│   ├── category.html
+│   ├── categories.html
+│   └── archives.html
+├── theme.yaml
+└── settings.yaml
+```
+
+详细说明：
+
+1. `/templates/` - 主题模板目录，存放主题模板文件，所有模板都需要放在这个目录。
+2. `/templates/assets/` - 主题静态资源目录，存放主题的静态资源文件，目前静态资源文件只能放在这个目录。
+3. `/theme.yaml` - 主题配置文件，配置主题的基本信息，如主题名称、版本、作者等。
+4. `/settings.yaml` - 主题设置定义文件，配置主题的设置项表单。
--- a/sidebars.js
+++ b/sidebars.js
@ -9,7 +9,7 @@
 Create as many sidebars as you want.
 */

- /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 module.exports = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
@ -69,6 +69,7 @@ module.exports = {
          label: "主题开发",
          items: [
            "developer-guide/theme/prepare",
+            "developer-guide/theme/structure",
            // "developer-guide/theme/config-files",
            // "developer-guide/theme/global-variable",
            // "developer-guide/theme/public-template-tag",