docs: refactor documentations of user guide (#225)

重构用户指南的部分内容。

/kind documentation

```release-note
None
```
JohnNiang-patch-1
Ryan Wang 1 year ago committed by GitHub
parent f9bbef1a63
commit 3ef8b4c0f9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -14,7 +14,7 @@ Halo 添加了 checkstyle 插件,来保证每位提交者代码的风格保持
- 进入 CheckStyle 配置File | Settings | Tools | Checkstyle
- 选择 Checkstyle 版本8.39。
- 在配置文件中点击添加按钮,配置描述可随便填写(推荐 Halo Checks选择 ./config/checkstyle/checkstyle.xml点击下一步和完成
- 在配置文件中点击添加按钮,配置描述可随便填写(推荐 Halo Checks选择 ./config/checkstyle/checkstyle.xml点击下一步和完成
- 勾选刚刚创建的配置文件。
## 配置 Editor

@ -3,27 +3,25 @@ title: 第一篇文章
description: 安装完成后,如何写下第一篇文章。
---
![第一篇文章](/img/first-post.gif)
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/first-post.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 登录管理端
浏览器访问 `$HALO_EXTERNAL_URL/console/`(外部访问链接)即可进入 Halo 管理端。默认的管理员用户名为 `admin`,登录密码为安装时设置的 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD`,文档中的默认值为 `P@88w0rd`。
浏览器访问 `/console` 即可进入 Halo 管理端。用户名密码为部署在配置文件中时设置的 `halo.security.initializer.superadminusername``halo.security.initializer.superadminpassword`。
:::info
如果你在安装时没有设置 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 变量或忘记了设置的密码,可以参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
如果你在安装时没有设置 `halo.security.initializer.superadminpassword` 变量或忘记了设置的密码,可以参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
:::
## 新建文章
Halo 安装完成后,默认初始化了一篇 `Hello Halo` 文章,接下来我们将创建并发布一篇自己的文章。
在 Halo 管理端,点击仪表盘页面中的 `创建文章` 快捷入口,即可进入到文章编辑页面。
在文章编辑器中,你可以尽情写下你想展现的内容。
当内容编辑完成后,点击右上角的 `发布` 按钮,给文章设置一个合适的标题和别名,同时可以设置文章所属分类、标签及其他一些高级设置。
确认无误后,点击弹框下方的 `发布` 按钮,我们的第一篇文章就成功发布了。
1. 在 Halo 管理端,点击仪表盘页面中的 `创建文章` 快捷入口,即可进入到文章编辑页面。
2. 在文章编辑器中,你可以尽情写下你想展现的内容。
3. 当内容编辑完成后,点击右上角的 `发布` 按钮,给文章设置一个合适的标题和别名,同时可以设置文章所属分类、标签及其他一些高级设置。
4. 确认无误后,点击弹框下方的 `发布` 按钮,我们的第一篇文章就成功发布了。
:::info
关于文章相关其他功能及文章各种设置项的说明,请参考《[用户指南-文章](../user-guide/posts.md)》章节
@ -33,6 +31,6 @@ Halo 安装完成后,默认初始化了一篇 `Hello Halo` 文章,接下来
文章发布成功后,就可以在主题端查看到我们刚刚创建的文章了。
浏览器访问 `$HALO_EXTERNAL_URL` 进入站点首页,站点展示的内容及样式由当前启用的主题所决定。
浏览器访问域名进入站点首页,站点展示的内容及样式由当前启用的主题所决定。
接下来,选一款喜欢的主题,尽情体验 Halo 吧!

@ -7,11 +7,16 @@ description: 附件管理相关功能说明
为了能够更加灵活地管理附件的存储位置Halo 提供了存储策略的概念。
Halo 中支持多种类型的存储策略,你可以通过安装插件的方式对支持的存储策略类型进行扩展。一个存储策略包含了存储提供者,具体存储位置等使用该类型存储所必要的各种信息。
Halo 默认提供了本地的存储策略类型,你还可以通过安装插件的方式扩展其他的存储策略类型。一个存储策略包含了存储提供者,具体存储位置等使用该类型存储所必要的各种信息。
你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
:::info
目前 Halo 官方维护了两个存储策略插件,可以根据需要选择安装:
1. 阿里云 OSS<https://halo.run/store/apps/app-wCJCD>
2. Amazon S3 协议(主流云存储厂商均支持):<https://halo.run/store/apps/app-Qxhpp>
:::
![存储策略](/img/user-guide/attachments/attachment-policy.png)
你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
### 新建存储策略
@ -19,19 +24,21 @@ Halo 中支持多种类型的存储策略,你可以通过安装插件的方式
![添加存储策略](/img/user-guide/attachments/attachment-policy-add.png)
添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `Aliyun OSS` 阿里云的 OSS 对象存储由[该插件](https://github.com/halo-sigs/plugin-alioss)提供
添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `S3 Object Storage` 由[对象存储Amazon S3 协议)](https://halo.run/store/apps/app-Qxhpp)提供,此文档以本地存储为例
![添加本地存储策略](/img/user-guide/attachments/attachment-policy-add-local.png)
添加一个本地存储时,你需要输入名称及存储位置信息。其中的存储位置决定了使用该存储策略的附件,在服务器上的实际存储路径,路径规则为 `{Halo 工作目录}/attachments/{存储位置}`,其中的 Halo 工作目录由安装时指定的参数决定,默认为 `~/.halo2`
:::info
默认的 Docker 部署方式,实际存储位置由挂载到 Halo 容器工作目录的服务器目录所决定。
:::
### 删除存储策略
### 管理存储策略
点击存储策略列表指定存储所在行后方的 `···` 更多操作按钮即可对该存储策略进行编辑或删除。
![存储策略操作](/img/user-guide/attachments/attachment-policy-operate.png)
:::info
为了保护附件安全避免用户误操作,当存储策略下存在附件时,该存储策略不允许删除。如果确定要删除某个存储策略及该存储策略中的所有附件,可以先按照存储策略对附件进行筛选,先批量删除存储策略下的所有附件,再删除存储策略。
:::
@ -54,49 +61,48 @@ Halo 中支持多种类型的存储策略,你可以通过安装插件的方式
Halo 目前提供了两种分组删除策略:
1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中
1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中
2. **删除并同时删除附件**:先删除下的所有附件后,再删除该分组。
:::warning
当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。
:::
:::warning
当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。
:::
## 上传附件
点击附件列表右上方的 `上传` 按钮即可上传新的附件到 Halo。
:::info
附件会被上传到当前选中的分组中,如果选择的是 `全部` 附件,则附件会被默认上传到 `未分组` 中。
:::
![上传附件](/img/user-guide/attachments/attachment-upload.png)
上传附件时你需要先选择一个存储策略,后续上传的附件将会存储在选中的存储策略中。
你可以点击 `浏览``我的设备` 图标唤起本地文件管理器进行文件选择,也可以直接将文件拖拽到待上传文件区域中。
![上传多个附件](/img/user-guide/attachments/attachment-upload-multiple.png)
如上图所示,你可以同时添加多个文件一次性完成多个附件的上传。
1. **分组选择**:你可以选择需要上传到的分组,为了方便,选择之后会在浏览器记住这个选项。
2. **存储策略选择**:你可以选择需要使用的存储策略,为了方便,选择之后会在浏览器记住这个选项。
3. **上传区域**:同时支持拖拽文件、点击上传区域选择文件、粘贴文件。
## 查看附件
点击附件列表中的某一个附件即可查看该附件的详细信息。
:::info
对于存储策略类型为本地存储的附件,详细信息中的的原始链接生成规则为 `/upload/{存储策略存储路径}/{文件名称}`
:::
![附件详情](/img/user-guide/attachments/attachment-detail.png)
1. **预览区域**:目前支持图片、视频、音频的预览。
2. **链接**目前可以显示并复制链接、HTML 格式代码、Markdown 格式代码。
## 删除附件
附件页面提供两种浏览模式,列表模式和平铺模式
目前有两种删除附件的方式,你可以选中一些附件进行批量删除或者点击指定附件所在行后方的 `···` 更多按钮,对单个附件进行删除操作
在平铺模式下,你可以点击附件缩略图右上角的 `√` 图标选中若干个附件,通过上方的批量操作按钮删除选中的附件。
![批量操作附件](/img/user-guide/attachments/attachment-batch-operate.png)
在列表模式下,你可以点击指定附件所在行后方的 `···` 更多按钮,对附件进行删除操作。
:::warning
附件删除后不可恢复、无法找回,请谨慎进行该操作。
:::
## 移动附件所在分组
## 移动附件
![附件移动](/img/user-guide/attachments/attachment-move.png)
与批量删除操作类似,你可以选中多个附件后在上方的批量操作按钮中选择 `移动` 操作,将所选附件移动到指定的分组中。
:::info
需要注意的是,目前移动附件只支持移动分组,不支持存储策略的移动。
:::

@ -11,18 +11,18 @@ Halo 作为一款好用又强大的开源建站工具,配合上不同的模板
控制台是一个 Halo 站点的后台管理系统,只有具有权限的登录用户才可以正常使用控制台功能。你可以在控制台中管理站点中的文章、页面、附件等各种内容,调整站点使用的主题或各种设置。
:::info
控制台默认地址为 `$HALO_EXTERNAL_URL/console/`。忘记密码请参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
控制台的访问入口为 `/console`。忘记密码请参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
:::
### 界面说明
![控制台界面说明](/img/user-guide/common/控制台界面说明.png)
1. **全局搜索框**:点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框,输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索
2. **侧边导航栏**:对控制台提供的功能进行导航,点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目
3. **用户信息展示及操作**:展示当前登录用户的头像、名称及角色等信息,`···` 中提供更多用户相关操作
4. **功能页面标题** 当前所在的功能页面标题
5. **功能页面操作区域**:当前所在功能页面提供的功能操作按钮
1. **全局搜索框**:点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框,输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索
2. **侧边导航栏**:对控制台提供的功能进行导航,点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目
3. **用户信息展示及操作**:展示当前登录用户的头像、名称及角色等信息,`···` 中提供更多用户相关操作
4. **功能页面标题** 当前所在的功能页面标题
5. **功能页面操作区域**:当前所在功能页面提供的功能操作按钮
6. **功能页面主体** 当前所在功能页面的主体显示区域,显示内容及形式视具体页面功能而定。
## 文章
@ -33,19 +33,11 @@ Halo 作为一款好用又强大的开源建站工具,配合上不同的模板
## 页面
Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`
### 功能页面
功能页面通常由各个插件提供,页面功能及在控制台呈现的内容由具体提供该页面的插件决定。
### 自定义页面
自定义页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
## 分类
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
通过分类可以更好地组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
## 标签
@ -59,14 +51,13 @@ Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`。
包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。
:::info
当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
:::
## 插件
用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。
:::info
当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
目前有两个官方渠道可以获取主题和插件:
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::

@ -1,172 +0,0 @@
---
title: 功能配置
description: 系统功能的相关配置说明
---
## 修改博客地址
很多人在部署完成之后都会惊奇的发现,博客前台居然没有样式?究其原因就是无法获取到静态资源,那么为什么获取不到呢?那就是你的博客地址没有设置正确。
第一步:
登录到后台之后,进入 博客设置 -> 常规设置。
第二步:
修改你的博客地址:
- 如果你没有进行域名解析或者没有配置反向代理,那么博客地址一般为 `http://ip:端口`
- 如果你进行了域名解析且配置了反向代理,但是没有配置 SSL 证书,那么博客地址一般为 `http://域名`
- 如果你进行了域名解析、配置了反向代理、也配置了 SSL 证书,那么博客地址一般为 `https://域名`
说了这么多,就是希望你别把 `http://` 或者 `https://` 搞混了。
另外,需要注意的是,地址尾部不需要 `/`
## 注册 Gravatar
很多人反映评论中自己的头像不显示,其实评论部分调用的头像并不是在个人资料中设置的那个,而是 `Gravatar`。所以这一点怪我,从 Halo 发布至今我都没有说明这个事情。
至于什么是 `Gravatar`,引用 `Gravatar` 官方的说明:`全球公认的头像`。这可不是在吹牛,因为只要接入了 Gravatar 的网站,你在网站上使用在 Gravatar 注册的邮箱之后,都会显示你设置的头像,而不需要额外设置。比较出名的网站有 `GitHub``GitLab``V2EX` 等。所以点击 <https://cn.gravatar.com/> 注册一个吧。
## 设置用户头像/Logo/Favicon
### 头像
第一步:
登录到后台之后,进入 用户 -> 个人资料。
第二步:
点击左侧头像即可选择本地附件中的图片。另外,也支持设置为 `Gravatar` 头像。点击 `使用 Gravatar` 即可。当然,前提是你注册了 `Gravatar` 才行。
### Logo/Favicon
第一步:
登录到后台之后,进入 系统 -> 博客设置。
第二步:
在常规设置中找到 Logo/Favicon 输入框,点击输入框后面的按钮即可调用附件库选择图片。
## SEO 设置
先说说程序本身对 SEO 做的优化:
- 支持 sitemap 站点地图:可访问 /sitemap.xml 或 /sitemap.html
- 全站绝对路径
- 页面静态化
- 支持伪静态1.3.0+
需要自己设置的有:
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> SEO 设置。
第二步:
填写你需要的一些关键词和博客描述,这部分可能需要你了解一定的 SEO 优化技巧。
> 另外,文章和自定义页面都可以自行设置关键词和描述(文章设置的高级设置中)。当然,你也可以不设置,系统为自动取你设置的文章标签为关键词,描述会自动取文章的部分内容。
Q&A
Q我刚发布的文章为啥百度搜索不到呢
A这是一件非常正常的事情建议注册百度的站长工具手动或者自动提交链接。
## SMTP 服务
SMTP 服务,简称发信服务,顾名思义就是用来发邮件的。那么,为什么要设置这个呢?有两个用途:
1. 评论通知,收到评论之后发信通知博主,评论者被回复之后发信通知被评论者。
2. 找回密码。
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> SMTP 设置。
第二步:
勾选 `是否启用`,并配置相关信息:
1. SMTP 地址到邮箱服务商查询。举两个例子QQ 邮箱smtp.qq.com163 邮箱smtp.163.com
2. 发送协议:一般不修改,具体可到邮箱服务商查询。
3. SSL 端口:一般不修改,具体可到邮箱服务商查询。
4. 邮箱账号:你的账号。
5. 邮箱密码:你的密码。
6. 发件人:随意。
第三步:
点击发送测试,填上你可以接收到的邮箱,并填写测试内容,最后点击发送。不出意外就可以发送成功,失败了就检查下配置吧。
Q&A
Q发送失败
A先检查配置是否有误如不知道哪里错误请查看日志。点击左上角 `Halo Dashboard`即可进入开发者选项,点击 `实时日志` 即可看到最近的日志。
Q日志说我授权出错但是我密码明明是对的啊
A部分邮箱所谓的密码并不是你的登陆密码需要去邮箱服务商生成 `授权码`。这个才是你需要填写的。
## 设置统计代码
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> 其他设置。
第二步:
`网站统计平台` 提供给你的一串代码填写到 `统计代码` 即可。
Q&A
Q什么是网站统计平台
A诸如百度统计CNZZGoogle Analytics。可以非常详细的统计你网站的访问情况。
## 找一个合适自己的主题
当你搭建好博客之后,如果你不喜欢默认的主题,那么你可以去 [https://halo.run/themes/](https://halo.run/themes/) 选择你喜欢的主题。在这里主要讲一些注意事项。
### 如何安装?
登录到后台之后,进入 外观 -> 主题,在后下角有一个按钮,点击之后选择 `安装主题`。系统提供的两种安装方式。
1. 第一种,远程拉取。你只需要把主题的 GitHub 地址复制进去点击下载即可。
2. 第二种本地上传你需要将主题安装包releases下载到本地然后选择 `本地上传` 点击选择你下载好的主题即可。
> 一般情况下,推荐第二种,第一种一般安装的为开发版本,建议谨慎使用。
### 设置主题
> 可能有一部分人不太清楚,一般情况下,每个主题都是有单独的设置选项的。
点击主题下方的设置按钮即可进入主题设置。另外主题设置还有一种预览模式,可以实时查看主题设置变更后的效果。当你设置当前激活主题的时候,在页面右下角有一个 `预览模式` 的按钮,点击即可进入预览模式。
## 设置备案信息
由于后台博客设置并没有提供设置备案信息的选项,所以有很多人不知道该怎么添加备案信息,这里简单说明一下。
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> 常规设置。
这时候你应该可以看到一个`页脚信息`的选项,而且有提示 `支持 HTML 格式的文本`。所以我们把备案信息放在这里即可。
第二步:
将整理好的备案信息填写到页脚信息即可,如果没记错的话,公安联网备案是有提供`网站公安机关备案号`和`备案编号HTML代码`的。

@ -9,7 +9,7 @@ description: 使用上的常见问题
### 忘记密码怎么办?
如果安装时没有指定 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量,系统会随机一个初始化密码,可以通过下面的命令进行查看。
如果安装时没有指定 `halo.security.initializer.superadminpassword` 参数,系统会随机一个初始化密码,可以通过下面的命令进行查看。
```bash
docker logs halo | grep 'Generated random password:' | tail -1
@ -25,7 +25,7 @@ docker logs halo | grep 'Generated random password:' | tail -1
docker stop halo
```
2. 连接 Halo 使用的数据库,删除 admin 用户记录
2. 连接 Halo 使用的数据库,删除管理员的用户记录(配置文件中的 `halo.security.initializer.superadminusername`),这里以 `admin` 为例
以容器化部署的 PostgreSQL 为例,假设容器名称为 `halo_db`
@ -49,7 +49,7 @@ docker logs halo | grep 'Generated random password:' | tail -1
4. 登录 Halo 控制台
如果部署时通过 `HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME` 和 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量指定了初始化用户名和密码,使用该用户名密码登录控制台。
如果部署时通过 `halo.security.initializer.superadminusername` 和 `halo.security.initializer.superadminpassword` 参数指定了初始化用户名和密码,使用该用户名密码登录控制台。
如果未指定该配置,则默认用户名为 `admin`,默认密码将打印在 Halo 容器日志中,可以通过如下命令查看。
@ -57,16 +57,6 @@ docker logs halo | grep 'Generated random password:' | tail -1
docker logs halo | grep 'Generated random password:' | tail -1
```
### 为什么百度无法搜索到我的站点?
这是一个暂时无法解答的问题。所涉及到的问题过多,受影响因素可能有域名、服务器 IP 位置、建站时间、网站结构、内容等等。建议了解一下 SEO 相关知识对网站进行优化,目前我们在程序方面做的优化有:
- 支持 sitemap 站点地图:可访问 `/sitemap.xml``/sitemap.html`
- 全站绝对路径
- 页面静态化
- 支持自定义文章关键字和描述
- 支持自定义站点关键字以及站点描述
### 附件上传提示 `413 Request Entity Too Large` 如何解决?
这可能是由于 Nginx 的上传大小限制所导致的。可以在 Nginx 的配置文件下的 server 节点加入 `client_max_body_size 1024m;` 即可解决,如果 1024m 还不够,请自行断定,详细配置参考如下:
@ -110,34 +100,37 @@ server {
-it -d \
--name halo-1 \
-p 8090:8090 \
-v ~/.halo2.1:/root/.halo2 \
-e HALO_EXTERNAL_URL=http://localhost:8090/ \
-e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
halohub/halo:2.6
-v ~/.halo2:/root/.halo2 \
halohub/halo:2.6 \
--halo.external-url=http://localhost:8090/ \
--halo.security.initializer.superadminusername=admin \
--halo.security.initializer.superadminpassword=P@88w0rd
# 第二个 Halo 容器
docker run \
-it -d \
--name halo-2 \
-p 8090:8090 \
-v ~/.halo2.2:/root/.halo2 \
-e HALO_EXTERNAL_URL=http://localhost:8090/ \
-e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
halohub/halo:2.6
-p 8091:8090 \
-v ~/.halo2_2:/root/.halo2 \
halohub/halo:2.6 \
--halo.external-url=http://localhost:8091/ \
--halo.security.initializer.superadminusername=admin \
--halo.security.initializer.superadminpassword=P@88w0rd
```
更多 Docker 相关的教程请参考:[使用 Docker 部署 Halo](../getting-started/install/docker.md)
### 如何查看运行日志?
使用 docker logs 命令进行查看。
1. 可以在 Console 端的概览页面下载最近的日志文件。
2. 使用 docker logs 命令进行查看。
```bash
# '-f' 滚动更新日志
# '-n 200' 从倒数第200行开始查看
# 更多帮助可以查看 'docker logs --help'
docker logs -f halo_next -n 200
```
```bash
# '-f' 滚动更新日志
# '-n 200' 从倒数第200行开始查看
# 更多帮助可以查看 'docker logs --help'
docker logs -f halo -n 200
```
### 前台样式丢失,如何解决?

@ -1,454 +0,0 @@
---
title: Markdown 语法
description: Halo 编辑器中所支持的 Markdown 语法说明
---
## 写在前面
从 1.5.0 版本开始Halo 默认保存编辑器渲染的 html 文档。使用的 Markdown 渲染库为 [markdown-it](https://github.com/markdown-it/markdown-it),我们也对此进行了封装:[@halo-dev/markdown-renderer](https://github.com/halo-dev/js-sdk/tree/master/packages/markdown-renderer)。后续我们会在任何需要渲染 Markdown 的地方都使用此库,保证 Markdown 渲染结果一致。
## 基础语法
markdown-it 使用了 [CommonMark spec](https://spec.commonmark.org) 规范,基础语法请参考 [CommonMark spec](https://spec.commonmark.org)。
## 自动链接Auto Link
支持自动将一个链接格式的文本转换为 a 标签链接。
语法规则:
```plain
https://halo.run
```
渲染结果:
```html
<a href="https://halo.run">https://halo.run</a>
```
预览:
<https://halo.run>
## 代码块Code Block
语法规则:
````markdown {1}
```language
内容
```
````
示例:
````markdown {1}
```java
public static void main(String[] args){
System.out.println("Hello World!");
}
```
````
````markdown {1}
```javascript
console.log("Hello World!")
```
````
:::info
注意:代码高亮需要主题添加插件支持,不同的主题可能有实现差异。
:::
## 缩写abbr
语法规则:
```markdown
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
The HTML specification
is maintained by the W3C.
```
渲染结果:
```html
<p>
The
<abbr title="Hyper Text Markup Language">
HTML
</abbr>
specification
<br />
is maintained by the
<abbr title="World Wide Web Consortium">
W3C
</abbr>
.
</p>
```
## Attrs
此语法支持将 `id` `class` `target` 添加到渲染后的 HTML 标签上。
示例:
```markdown
# Halo {#halo}
```
```markdown
> Hello Halo {.info}
```
```markdown
[https://halo.run](https://halo.run) {target="_blank"}
```
渲染结果:
```html
<h1 id="halo" tabindex="-1">Halo</h1>
```
```html
<blockquote class="info"> <p>Hello Halo</p> </blockquote>
```
```html
<a href="https://halo.run" target="_blank">https://halo.run</a>
```
## Emoji
支持将 Emoji 的文字形式转化为图片形式。
示例:
```markdown
:100:
```
渲染结果:
```html
💯
```
## 脚注Footnote
语法规则:
```markdown
[^脚注名]
[^脚注名]: 脚注内容
```
示例:
```html
驿外[^1]断桥边,寂寞开无主。已是黄昏独自愁,更着风和雨
[^1]: 驿指荒僻、冷清之地。驿驿站。
```
渲染结果:
```html
<p>
驿外
<sup class="footnote-ref">
<a href="#fn1" id="fnref1">
[1]
</a>
</sup>
断桥边,寂寞开无主。已是黄昏独自愁,更着风和雨
</p>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1" class="footnote-item">
<p>
驿指荒僻、冷清之地。驿驿站。
<a href="#fnref1" class="footnote-backref">
↩︎
</a>
</p>
</li>
</ol>
</section>
```
## 下划线ins
示例:
```markdown
++inserted++
```
渲染结果:
```html
<ins>inserted</ins>
```
预览:
<ins>inserted</ins>
## 标记mark
示例:
```markdown
==marked==
```
渲染结果:
```html
<mark>marked</mark>
```
预览:
<mark>marked</mark>
## 下标sub
示例:
```markdown
H~2~0
```
渲染结果:
```html
H<sub>2</sub>0
```
预览:
H<sub>2</sub>0
## 上标sup
示例:
```markdown
29^th^
```
渲染结果:
```html
29<sup>th</sup>
```
预览:
29<sup>th</sup>
## 目录TOC
此语法支持根据标题生成文档目录。
示例:
```markdown
[toc]
# Heading
## Sub heading 1
Some nice text
## Sub heading 2
Some even nicer text
```
渲染结果:
```html
<p>
<div class="table-of-contents">
<ul>
<li>
<a href="#heading">
Heading
</a>
<ul>
<li>
<a href="#sub-heading-1">
Sub heading 1
</a>
</li>
<li>
<a href="#sub-heading-2">
Sub heading 2
</a>
</li>
</ul>
</li>
</ul>
</div>
</p>
<h1 id="heading" tabindex="-1">
Heading
</h1>
<h2 id="sub-heading-1" tabindex="-1">
Sub heading 1
</h2>
<p>
Some nice text
</p>
<h2 id="sub-heading-2" tabindex="-1">
Sub heading 2
</h2>
<p>
Some even nicer text
</p>
```
## 任务列表Task Lists
示例:
```markdown
- [x] Apple
- [ ] Banana
```
渲染结果:
```html
<ul class="contains-task-list">
<li class="task-list-item">
<input class="task-list-item-checkbox" checked="" disabled="" type="checkbox">
Apple
</li>
<li class="task-list-item">
<input class="task-list-item-checkbox" disabled="" type="checkbox">
Banana
</li>
</ul>
```
预览:
- [x] Apple
- [ ] Banana
## 数学公式Katex
我们使用了 KaTeX 作为数学公式渲染的插件,因为从 1.5.0 开始,我们将直接保存编辑器渲染的内容,在保存的时候就已经保存了渲染好的 KaTeX 结构。所以在前台无需引入 KaTeX 插件来进行渲染,但目前仍需要引入 KaTeX 的样式文件,如果主题没有支持,可以在系统设置的 `自定义内容页 head` 中加入以下代码:
```html
<link rel="stylesheet" href="https://unpkg.com/katex@0.12.0/dist/katex.min.css" />
```
### 行内公式
示例:
```markdown
$\sqrt{3x-1}+(1+x)^2$
```
预览:
Example$\sqrt{3x-1}+(1+x)^2$
### 块级公式
示例:
```markdown
$$\begin{array}{c}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{array}$$
```
预览:
$$\begin{array}{c}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{array}$$
## 图表Mermaid
从 Halo 1.5.0 开始,编辑器支持渲染 Mermaid 图表为 svg 内容,并直接保存渲染后的内容,所以无需在前台引入 Mermaid 插件进行渲染。
示例:
````markdown
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
````
````markdown
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
````
预览:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
## 短连接
参考 [1.4.17/Markdown 语法](../../versioned_docs/version-1.4/user-guide/markdown.md#短连接)。目前已经在 1.5.x 移除,建议直接使用官方提供的嵌入代码。

@ -3,39 +3,18 @@ title: 页面
description: 页面管理相关功能说明
---
Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`
页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等
### 功能页面
自定义页面的访问链接为 `/{slug}` 其中 `slug` 为自定义页面的别名。
功能页面通常由各个插件提供,页面功能及在控制台呈现的内容由具体提供该页面的插件决定
对于如下的关于页面,便可以通过 `/about` 地址进行访问
例如[链接插件](https://github.com/halo-sigs/plugin-links)便实现了一个站点链接管理功能,用户可以通过该插件更加方便地管理与站点相关的友情链接。安装该插件后,在功能页面会出现列表会出现如下条目。
![链接功能页面](/img/user-guide/pages/page-links.png)
点击这个条目即可进入到链接插件提供的配置管理页面。
![链接功能页面](/img/user-guide/pages/page-links-edit.png)
你可以在这个页面中管理链接分组和链接条目。链接信息维护完成后,通过 `$HALO_EXTERNAL_URL/links/` 便可访问到对应的页面。
:::info
对于 `links` 页面的访问需要主题端支持,即安装使用的主题需要有对应的 `links.html` 模板,且在模板中正确处理链接插件提供的数据。
:::
### 自定义页面
自定义页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
自定义页面的访问链接为 `$HALO_EXTERNAL_URL/{slug}/` 其中 `slug` 为自定义页面的别名。
对于如下的关于页面,便可以通过 `$HALO_EXTERNAL_URL/page/` 地址进行访问。
![链接功能页面](/img/user-guide/pages/page-about.png)
:::info
自定义页面默认使用主题端的 `page.html` 模板进行渲染,如果主题中提供了针对自定义页面的其他模板,用户可以通过修改自定义页面高级设置中的自定义模板设置进行使用。
:::
#### 自定义页面操作
#### 页面操作
对于自定义页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南-文章》](./posts.md)章节,此处不再赘述。
对于页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南-文章》](./posts.md)章节,此处不再赘述。

@ -5,19 +5,41 @@ description: 插件管理相关功能说明
插件时用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。
本文档仅对插件的基本管理功能进行说明,关于插件的详细使用说明请参考对应插件的文档。
:::info
当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
:::
目前有两个官方渠道可以获取插件:
本文档仅对插件的基本管理功能进行说明,关于插件的详细使用说明请参考对应插件的文档。
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::
## 安装插件
点击插件页面右上角的 `安装` 按钮,在弹出的文件上传对话框中上传插件文件即可完成插件安装。
进入插件管理页面,点击右上角的 `安装` 按钮即可打开插件安装的对话框。
和主题一样,插件同时支持本地上传安装和远程下载安装。
### 本地上传安装
![安装插件](/img/user-guide/plugins/plugin-install.png)
插件安装成功后,便会出现在已安装主题列表中。你可以点击某个插件进入到插件详情页面。
插件安装成功后,便会出现在插件管理的列表中。
### 远程下载安装
同样,在安装插件的对话框中,切换到远程下载选项卡,输入插件的下载地址,点击 `下载` 按钮即可开始下载插件。
插件安装成功后,便会出现在插件管理的列表中。
此外, Halo 的[应用市场](https://halo.run/store/apps)也支持通过输入站点地址的方式自动跳转到你的站点进行安装,演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/install-plugin-from-store.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
:::info
插件安装成功后会提示你是否需要启动该插件,你可以根据需要选择是否启动。
:::
## 插件设置
@ -25,7 +47,7 @@ description: 插件管理相关功能说明
![插件设置](/img/user-guide/plugins/plugin-setting.png)
以 Unsplash 插件为例,该提供仅在基本设置组中提供了 `Access Key` 一项配置,用于调用 Unsplash 接口
此处以 `plugin-umami` 插件为例
:::info
你可以点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将插件提供的设置项恢复为默认值。
@ -39,11 +61,16 @@ description: 插件管理相关功能说明
## 升级插件
点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `升级` 选项即可上传新的插件文件对当前插件进行升级。
点击具体插件的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级插件的对话框,与安装插件一样,同时支持本地上传和远程下载。
## 重置
如果你需要清空所有插件配置并重新配置插件,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。
## 卸载插件
点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前插件进行卸载。
![卸载插件](/img/user-guide/plugins/plugin-uninstall.png)
:::info

@ -7,58 +7,52 @@ description: 文章管理相关功能说明
目前你可以通过以下两种方式新建一篇文章:
1. 点击仪表盘快捷访问组件中的创建文章
:::info
仪表盘中需要存在快捷访问组件(默认存在)。关于仪表盘组件配置,请参考《用户指南-仪表盘》章节。
:::
2. 通过左侧导航栏进入文章页面,点击右上角的新建按钮
进入到如下页面后,你就可以开始编辑自己的文章内容了:
![文章编辑界面说明](/img/user-guide/posts/post-edit.png)
在文章编辑器中输入你想展现的内容,你可以通过编辑器上方的工具栏调整指定内容的格式或者插入图片、音视频等各类附件。编辑器还提供了各种快捷指令,通过输入 `/` 字符便可以快速选择常用的输入类型,不需要操作鼠标便可以轻松完成文章排版。
1. **编辑器切换**:如果安装了其他的编辑器插件,那么就可以在这个位置选择所需的编辑器。
2. **预览**:点击预览按钮可以在未发布的时候预览文章的渲染效果。
3. **保存**:仅保存文章内容,但是不发布。
4. **发布**:保存并发布文章内容。
:::info
编辑器详细使用说明请参考[《用户指南-编辑器》](./posts.md)。
Halo 支持通过插件来拓展文章编辑器,目前 Halo 官方维护了另外两款编辑器插件,可以按需安装使用:
如果安装并启用了额外的编辑器插件,可以点击右上角切换使用不同的编辑器。以下文档内容均使用默认编辑器进行说明。
:::
在页面右侧你可以看到文章的大纲结构及字词数等详细信息。一切满意之后,你可以选择暂存这篇文章的草稿或直接将文章进行发布。
:::info
点击保存按钮将只保存文章内容的修改,不会将新修改的内容进行发布。对于未发布的文章内容,只有授权用户可以在控制台进行查看,不会出现在站点内容中;
点击发布按钮将直接发布修改后的内容。对于已发布的文章,默认可以通过站点地址进行公开访问,用户可以在文章高级设置中修改可见性。
1. StackEdit<https://halo.run/store/apps/app-hDXMG>
2. ByteMD<https://halo.run/store/apps/app-HTyhC>
:::
## 文章设置
当你想修改一篇文章的标题、所属分类等信息时,你可以通过以下方式进行操作:
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择设置
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择设置。
2. 在文章列表点击指定文章的标题进入文章编辑页面,点击页面右上角的设置按钮。
![文章编辑界面说明](/img/user-guide/posts/post-setting.png)
### 设置说明
- **标题**:用于在主题端显示的文章标题
- **别名**多用于文章 URL 路径定位,一般不会出现在页面中;
- **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类
- **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签
- **自动生成摘要**:文章摘要是对文章内容的概括性描述
- **是** 系统根据文章内容,自动生成一段摘要文本;
- **标题**:用于在主题端显示的文章标题
- **别名**通常用于生成文章访问地址,如:`/archives/{slug}`。
- **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类
- **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签
- **自动生成摘要**:文章摘要是对文章内容的概括性描述
- **是** 系统根据文章内容,自动生成一段摘要
- **否** 用户自行输入文章摘要文本。
- **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论;
- **是否置顶**:文章是否排序在文章列表的最顶部;
- **可见性**:访问站点主题端时,哪些人可以看到这篇文章;
- **公开**:所有用户均可看到这篇文章,包括未登录用户;
- **自定义摘要**:用户自行输入的文章摘要文本,仅当 `自动生成摘要` 为否时生效。
- **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论。
- **是否置顶**:文章是否排序在文章列表的最顶部。
- **可见性**:访问站点主题端时,哪些人可以看到这篇文章。
- **公开**:所有用户均可看到这篇文章,包括未登录用户。
- **私有**:仅文章作者可以看到这篇文章。
- **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准
- **自定义模板**主题端使用哪一个文章模板进行页面渲染;
- **封面图**用户在主题端显示的文章封面图,需要主题支持该功能;
- **元数据**:供主题、插件使用的额外数据信息。例如 Halo 官网主题仓库中的主题,便可以使用该功能为主题类型的文章增加一条名为下载地址的元数据,提供对应主题的下载链接
- **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准
- **自定义模板**自定义文章的渲染模板,由主题提供支持。
- **封面图**文章封面图设置,需要主题支持该功能。
- **元数据**:供主题、插件使用的额外数据信息。比如主题在文章页面提供了一个下载按钮,那么就可以通过元数据来指定下载地址
## 发布及取消发布
@ -66,13 +60,13 @@ description: 文章管理相关功能说明
你可以在上文介绍的文章设置对话框中,修改文章的发布状态。
在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮;若文章处于未发布状态,下方怎会显示发布按钮。
在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮。若文章处于未发布状态,下方则不会显示发布按钮。
## 删除文章
当你不再需要一篇文章时,你可以通过以下方式删除该文章:
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除
2. 勾选文章列表中的全选/多选框,选中一篇或多篇文章进行批量删除。
文章删除后会进入回收站中,点击右上角的回收站按钮进入回收站。在回收站中,你可以永久删除或恢复指定的文章。
@ -83,7 +77,7 @@ description: 文章管理相关功能说明
## 文章分类管理
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
在文章管理页面,点击页面右上角的 `分类` 按钮即可进入分类管理页面。
@ -95,11 +89,11 @@ description: 文章管理相关功能说明
#### 设置说明
- **名称**:用于在主题端显示的分类名称
- **别名**用于分类 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/categories/{slug}`,其中 `slug` 为分类别名,访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](./settings#主题路由设置)
- **自定义模板**主题端使用哪一个文章分类模板进行页面渲染;
- **封面图**用户在主题端显示的文章分类封面图,需要主题支持该功能;
- **描述**:关于改文章分类的更多描述信息;
- **名称**:用于在主题端显示的分类名称
- **别名**通常用于生成分类归档页面的访问地址。默认路径规则为 `/categories/{slug}`,其中 `slug` 为分类别名,访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](./settings#主题路由设置)
- **自定义模板**自定义分类归档页面的渲染模板,由主题提供支持。
- **封面图**分类封面图设置,需要主题支持该功能。
- **描述**:关于该文章分类的更多描述信息。
- **元数据**:供主题、插件使用的额外数据信息。例如部分主题期望使用不同的颜色对分类进行区分,便可以使用该功能为分类增加颜色相关的元数据。
### 调整分类层级
@ -110,9 +104,10 @@ description: 文章管理相关功能说明
![移动文章分类](/img/user-guide/posts/category-move.gif)
### 修改删除分类
### 修改/删除分类
点击指定分类所在行后方的 `···` 更多操作按钮,可以对文章分类进行修改或删除。
:::warning
文章分类删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。
:::
@ -129,22 +124,16 @@ description: 文章管理相关功能说明
#### 设置说明
- **名称**:用于在主题端显示的标签名称
- **别名**用于标签 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/tags/{slug}`,其中 `slug` 为标签别名,访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](./settings#主题路由设置)
- **颜色**:用于在控制台及主题端显示的标签颜色,主题端显示颜色需要主题支持该功能
- **封面图**用户在主题端显示的标签封面图,需要主题支持该功能;
- **名称**:用于在主题端显示的标签名称
- **别名**通常用于生成标签归档页面的访问地址。默认路径规则为 `/tags/{slug}`,其中 `slug` 为标签别名,访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](./settings#主题路由设置)
- **颜色**:用于在控制台及主题端显示的标签颜色,主题端显示颜色需要主题支持该功能
- **封面图**标签封面图设置,需要主题支持该功能。
- **元数据**:供主题、插件使用的额外数据信息。
### 修改删除标签
标签页面提供两种浏览模式,列表模式和平铺模式。点击右上方红框区域对应模式的切换按钮即可进行切换。
![标签浏览](/img/user-guide/posts/tag-list.png)
### 修改/删除标签
在列表模式下,点击指定标签所在行后方的 `···` 更多操作按钮,可以对文章标签进行修改或删除。
在平铺模式下,直接点击对应的标签,即可对文章标签进行修改。
:::warning
文章标签删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。
:::

@ -9,8 +9,8 @@ Halo 提供了以下站点基本信息设置:
- **站点标题**
- **站点副标题**
- **站点 Logo 图片**
- **站点 Favion 图片**
- **Logo**
- **Favicon**
在控制台设置完成后,主题端可以通过特定的表达式获取到这些信息并且在对应的位置进行展示。具体是否读取使用这些配置、在哪些位置显示这些信息由使用的不同主题而决定。
@ -27,30 +27,44 @@ Halo 提供了以下站点基本信息设置:
- **分类页文章显示条数**
- **标签页文章显示条数**
## SEO设置
## SEO 设置
针对站点的 SEO搜索引擎优化需求Halo 提供了以下设置项:
- **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="robots" content="noindex" />`
- **站点关键词**:格式为以`,`分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="keywords"> content="{用户的配置关键词}" />`
- **站点描述**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name=""> content="{用户的配置描述}" />`
- **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="robots" content="noindex" />`
- **站点关键词**:格式为以`,`分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="keywords"> content="{关键词}" />`
:::warning 注意
目前主流的搜索引擎(如 Google、Bing、百度搜索等已经不再使用该标签作为关键词的参考因此该设置项的作用已经不大未来我们也可能会移除该设置项。
:::
- **站点描述**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="description" content="{描述}" />`
## 用户设置
- **开放注册**:是否允许访客注册,勾选之后在登录页面会显示注册入口。
- **默认角色**:新注册用户的默认角色。
## 评论设置
针对站点的评论功能Halo 提供了以下设置项:
- **启用评论**:全局评论功能开关配置,修改后影响所有文章、页面的评论功能;
- **新评论审核**:新增的评论是否需要在控制台进行审核,审核通过后其他访问者才能看到该条评论;
- **仅允许注册用户评论**:开启后只有登录用户才能添加评论,关闭后匿名(未登录)访问者也可以添加评论。
- **启用评论**:全局评论功能开关配置,修改后影响所有文章、页面的评论功能
- **新评论审核**:新增的评论是否需要在控制台进行审核,审核通过后其他访问者才能看到该条评论
- **仅允许注册用户评论**:开启后只有登录用户才能添加评论,关闭后匿名(未登录)的访客也可以通过自行填写昵称、邮箱、网址等信息进行评论。
## 主题路由设置
针对访问站点各种类型页面的 URL 生成规则Halo 提供了以下主题路由设置项:
- **分类页路由前缀**:定位到指定文章分类页面的 URL 规则前缀,默认为 `/categories/{文章分类别名}`,修改后为 `/{用户定义的分类页路由前缀/{文章分类别名}`
- **标签页路由前缀**:定位到指定文章标签页面的 URL 规则前缀,默认为 `/tags/{文章标签别名}`,修改后为 `/{用户定义的标签页路由前缀/{文章标签别名}`
- **归档页路由前缀**:定位到文章归档页面的 URL 规则前缀,默认为 `/archives/{年}/{月}` 等路径,修改后为 `/{用户定义的归档页路由前缀/{年}/{月}` 等;
- **文章详情页访问规则**:定位到具体文章详情页面的 URL 规则前缀,默认为 `/archives/{文章别名}` ,用户可从以下路径规则进行选择:
- **分类页路由前缀**:定位到分类列表页面以及分类归档页面。
- 默认的分类列表页面 URL 规则前缀为 `/categories`
- 默认的分类归档页面 URL 规则前缀为 `/categories/{slug}`
- **标签页路由前缀**:定位到标签列表页面以及标签归档页面。
- 默认的标签列表页面 URL 规则前缀为 `/tags`
- 默认的标签归档页面 URL 规则前缀为 `/tags/{slug}`
- **归档页路由前缀**:定位到文章归档页面的 URL 规则前缀,默认为 `/archives`
- **文章详情页访问规则**:定位到具体文章详情页面的 URL 规则前缀,默认为 `/archives/{slug}` ,用户可从以下路径规则进行选择:
- `/archives/{slug}`
- `/archives/{name}`
- `/?p={name}`
@ -59,14 +73,19 @@ Halo 提供了以下站点基本信息设置:
- `/{year}/{slug}`
- `/{year}/{month}/{slug}`
- `/{year}/{month}/{day}/{slug}`
:::info 变量说明
- `slug`:文章别名;
- `name`:文章 `metadata.name` 字段值;
- `year`:四位数格式的文章发布年份;
- `month`:两位数格式的文章发布月份:
- `day`:两位数格式的文章发布日。
:::
:::info 变量说明
- `slug`:文章别名
- `name`:文章 `metadata.name` 字段值
- `year`:四位数格式的文章发布年份
- `month`:两位数格式的文章发布月份
- `day`:两位数格式的文章发布日
:::
## 代码注入
你可以使用代码注入功能,在特定类型的页面中注入额外的代码。你可以通过该功能覆盖或补充部分主题 CSS 样式,或者引入额外的 JavaScript 脚本扩展主题端功能。
- **全局 head 标签**:该代码将会被注入到所有页面的 head 标签中。
- **内容页 head 标签**:该代码将会被注入到文章、页面详情页的 head 标签中。
- **页脚**:该代码将会被注入到所有页面的页脚中。

@ -4,41 +4,50 @@ description: 主题管理相关功能说明
---
主题包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。
:::info
当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
目前有两个官方渠道可以获取主题:
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::
## 安装主题
点击主题页面右上方的 `主题管理` 按钮即可弹出主题管理对话框。
目前 Halo 提供了两种主题安装方式
目前 Halo 提供了两种主题安装方式
1. 通过控制台上传安装
2. 将主题文件夹拷贝到服务器上的 `{Halo 工作目录}/themes/` 目录下等待 Halo 自动扫描
### 本地上传安装
针对第一种安装方式,你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的文件上传对话框中上传主题压缩包。
你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的安装主题对话框中上传主题压缩包。
![安装主题](/img/user-guide/themes/theme-install.png)
主题安装成功后,便会出现在已安装主题列表中。
针对第二种方式,你需要手动将解压后的主题文件夹拷贝到服务器上的指定目录下,如果主题校验通过,你便可以在主题列表的 `未安装` 标签页中看到该主题。
### 远程下载安装
同样,在安装主题的对话框中,切换到远程下载选项卡,输入主题的下载地址,点击 `下载` 按钮即可开始下载主题。
之后点击主题所在行后方的 `安装` 按钮,即可完成该主题的安装。
下载完成后,便会出现在已安装主题列表中
![后台安装主题](/img/user-guide/themes/theme-install-alt.png)
此外, Halo 的[应用市场](https://halo.run/store/apps)也支持通过输入站点地址的方式自动跳转到你的站点进行安装,演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/install-theme-from-store.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 切换主题
同样点击主题页面右上方的 `主题管理` 按钮弹出主题管理对话框。
在弹框中点击选中要切换的目标主题,此时页面返回到主题详情页,点击右上角的 `启用` 按钮即可将当前主题切换为实际使用的主题。
:::info
仅选中主题不点击右上角的 `启用` 按钮时,不会影响当前实际使用的主题。
:::
你也可以在已安装主题列表中,通过后方 ··· 的更多操作中的启用选项直接启用指定的主题。
你也可以在已安装主题列表中,通过后方 `···` 的更多操作中的启用选项直接启用指定的主题。
## 修改主题设置
@ -56,18 +65,25 @@ description: 主题管理相关功能说明
通过预览功能,你可以在不更改当前启用主题的情况下查看不同主题的效果。点击主题详情页面右上角的 `预览` 按钮预览当前主题,或者进入已安装主题列表,通过后方 `···` 的更多操作中的预览选项预览指定的主题。
![主题设置](/img/user-guide/themes/theme-preview.png)
在主题预览页面你可以切换不同分辨率的设备,模拟主题在不同终端下的显示效果。也可以通过右上角的功能菜单切换预览的主题,或者调整当前主题的设置,查看不同设置下主题所展现的区别。
演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/theme-preview.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 升级主题
点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可上传新的主题包对当前主题进行升级更新。
点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级主题的对话框,与安装主题一样,同时支持本地上传和远程下载
## 重载主题配置
如果当前主题提供的设置项发生变化,可以通过 `···` 更多操作中的 `重载主题配置` 选项对主题配置项进行更新。
## 重置
如果你需要清空所有主题配置并重新配置主题,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。
## 卸载主题
进入已安装主题列表,点击指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前主题进行卸载。

@ -7,10 +7,6 @@ description: 用户管理、权限配置相关功能说明
Halo 2.0 版本采用了基于角色的权限控制RBAC体系。不同于之前 1.x 版本的单用户设计,现在你可以创建多个用户并且通过赋予不同用户不同角色的方式,为他们分配不同的权限。
Halo 中的权限控制体系示例:
![权限控制体系示例](/img/user-guide/user-permission.png)
## 用户
点击左侧导航栏的 `用户` 条目进入用户管理页面。
@ -93,3 +89,23 @@ Halo 提供了全新创建和基于已有角色创建两种角色创建方式。
:::warning
删除角色后,分配了该角色的用户会丧失对应的权限,影响用户使用。此操作不可恢复。
:::
## 身份认证
目前 Halo 默认仅支持本地身份认证,但可以通过插件的方式拓展其他三方的身份认证方式。
:::info
目前 Halo 官方提供的身份认证插件:
- OAuth2 认证:<https://halo.run/store/apps/app-ESVDK>
:::
你可以在用户管理界面的右上角点击 `身份认证` 按钮,进入身份认证管理页面。
![身份认证](/img/user-guide/users/auth-providers-entry.png)
进入身份认证管理页面之后,如果你已经安装了提供身份认证方式的插件,你就可以在列表中看到对应的身份认证方式,你可以对其进行设置并启用。
![身份认证方式](/img/user-guide/users/auth-providers.png)
> 这里是安装了 [OAuth2 认证](https://halo.run/store/apps/app-ESVDK) 插件,提供了 `GitHub`、`GitLab`、`Gitee` 三种 OAuth2 认证方式。

@ -27,6 +27,12 @@
padding: 0 var(--ifm-pre-padding);
}
html[data-theme='dark'] .docusaurus-highlight-code-line {
html[data-theme="dark"] .docusaurus-highlight-code-line {
background-color: rgba(0, 0, 0, 0.3);
}
p > img {
border-radius: 0.4rem;
box-shadow: 2px 2px 0.4rem 2px rgba(0, 0, 0, 0.3);
overflow: hidden;
}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 191 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 308 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 159 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 168 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 121 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 127 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 86 KiB

After

Width:  |  Height:  |  Size: 192 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 99 KiB

After

Width:  |  Height:  |  Size: 198 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 131 KiB

After

Width:  |  Height:  |  Size: 215 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 126 KiB

After

Width:  |  Height:  |  Size: 233 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 72 KiB

After

Width:  |  Height:  |  Size: 131 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 127 KiB

After

Width:  |  Height:  |  Size: 222 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 242 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 138 KiB

After

Width:  |  Height:  |  Size: 217 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.5 MiB

After

Width:  |  Height:  |  Size: 2.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 165 KiB

After

Width:  |  Height:  |  Size: 273 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 248 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 120 KiB

After

Width:  |  Height:  |  Size: 192 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 118 KiB

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 123 KiB

After

Width:  |  Height:  |  Size: 175 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 116 KiB

After

Width:  |  Height:  |  Size: 150 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 153 KiB

After

Width:  |  Height:  |  Size: 201 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 148 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 170 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 130 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 162 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 111 KiB

After

Width:  |  Height:  |  Size: 177 KiB

@ -14,7 +14,7 @@ Halo 添加了 checkstyle 插件,来保证每位提交者代码的风格保持
- 进入 CheckStyle 配置File | Settings | Tools | Checkstyle
- 选择 Checkstyle 版本8.39。
- 在配置文件中点击添加按钮,配置描述可随便填写(推荐 Halo Checks选择 ./config/checkstyle/checkstyle.xml点击下一步和完成
- 在配置文件中点击添加按钮,配置描述可随便填写(推荐 Halo Checks选择 ./config/checkstyle/checkstyle.xml点击下一步和完成
- 勾选刚刚创建的配置文件。
## 配置 Editor

@ -3,27 +3,25 @@ title: 第一篇文章
description: 安装完成后,如何写下第一篇文章。
---
![第一篇文章](/img/first-post.gif)
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/first-post.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 登录管理端
浏览器访问 `$HALO_EXTERNAL_URL/console/`(外部访问链接)即可进入 Halo 管理端。默认的管理员用户名为 `admin`,登录密码为安装时设置的 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD`,文档中的默认值为 `P@88w0rd`。
浏览器访问 `/console` 即可进入 Halo 管理端。用户名密码为部署在配置文件中时设置的 `halo.security.initializer.superadminusername``halo.security.initializer.superadminpassword`。
:::info
如果你在安装时没有设置 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 变量或忘记了设置的密码,可以参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
如果你在安装时没有设置 `halo.security.initializer.superadminpassword` 变量或忘记了设置的密码,可以参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
:::
## 新建文章
Halo 安装完成后,默认初始化了一篇 `Hello Halo` 文章,接下来我们将创建并发布一篇自己的文章。
在 Halo 管理端,点击仪表盘页面中的 `创建文章` 快捷入口,即可进入到文章编辑页面。
在文章编辑器中,你可以尽情写下你想展现的内容。
当内容编辑完成后,点击右上角的 `发布` 按钮,给文章设置一个合适的标题和别名,同时可以设置文章所属分类、标签及其他一些高级设置。
确认无误后,点击弹框下方的 `发布` 按钮,我们的第一篇文章就成功发布了。
1. 在 Halo 管理端,点击仪表盘页面中的 `创建文章` 快捷入口,即可进入到文章编辑页面。
2. 在文章编辑器中,你可以尽情写下你想展现的内容。
3. 当内容编辑完成后,点击右上角的 `发布` 按钮,给文章设置一个合适的标题和别名,同时可以设置文章所属分类、标签及其他一些高级设置。
4. 确认无误后,点击弹框下方的 `发布` 按钮,我们的第一篇文章就成功发布了。
:::info
关于文章相关其他功能及文章各种设置项的说明,请参考《[用户指南-文章](../user-guide/posts.md)》章节
@ -33,6 +31,6 @@ Halo 安装完成后,默认初始化了一篇 `Hello Halo` 文章,接下来
文章发布成功后,就可以在主题端查看到我们刚刚创建的文章了。
浏览器访问 `$HALO_EXTERNAL_URL` 进入站点首页,站点展示的内容及样式由当前启用的主题所决定。
浏览器访问域名进入站点首页,站点展示的内容及样式由当前启用的主题所决定。
接下来,选一款喜欢的主题,尽情体验 Halo 吧!

@ -7,11 +7,16 @@ description: 附件管理相关功能说明
为了能够更加灵活地管理附件的存储位置Halo 提供了存储策略的概念。
Halo 中支持多种类型的存储策略,你可以通过安装插件的方式对支持的存储策略类型进行扩展。一个存储策略包含了存储提供者,具体存储位置等使用该类型存储所必要的各种信息。
Halo 默认提供了本地的存储策略类型,你还可以通过安装插件的方式扩展其他的存储策略类型。一个存储策略包含了存储提供者,具体存储位置等使用该类型存储所必要的各种信息。
你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
:::info
目前 Halo 官方维护了两个存储策略插件,可以根据需要选择安装:
1. 阿里云 OSS<https://halo.run/store/apps/app-wCJCD>
2. Amazon S3 协议(主流云存储厂商均支持):<https://halo.run/store/apps/app-Qxhpp>
:::
![存储策略](/img/user-guide/attachments/attachment-policy.png)
你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
### 新建存储策略
@ -19,19 +24,21 @@ Halo 中支持多种类型的存储策略,你可以通过安装插件的方式
![添加存储策略](/img/user-guide/attachments/attachment-policy-add.png)
添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `Aliyun OSS` 阿里云的 OSS 对象存储由[该插件](https://github.com/halo-sigs/plugin-alioss)提供
添加时首先需要选择一种存储策略类型,系统内置的存储策略为本地存储,图中的 `S3 Object Storage` 由[对象存储Amazon S3 协议)](https://halo.run/store/apps/app-Qxhpp)提供,此文档以本地存储为例
![添加本地存储策略](/img/user-guide/attachments/attachment-policy-add-local.png)
添加一个本地存储时,你需要输入名称及存储位置信息。其中的存储位置决定了使用该存储策略的附件,在服务器上的实际存储路径,路径规则为 `{Halo 工作目录}/attachments/{存储位置}`,其中的 Halo 工作目录由安装时指定的参数决定,默认为 `~/.halo2`
:::info
默认的 Docker 部署方式,实际存储位置由挂载到 Halo 容器工作目录的服务器目录所决定。
:::
### 删除存储策略
### 管理存储策略
点击存储策略列表指定存储所在行后方的 `···` 更多操作按钮即可对该存储策略进行编辑或删除。
![存储策略操作](/img/user-guide/attachments/attachment-policy-operate.png)
:::info
为了保护附件安全避免用户误操作,当存储策略下存在附件时,该存储策略不允许删除。如果确定要删除某个存储策略及该存储策略中的所有附件,可以先按照存储策略对附件进行筛选,先批量删除存储策略下的所有附件,再删除存储策略。
:::
@ -54,49 +61,48 @@ Halo 中支持多种类型的存储策略,你可以通过安装插件的方式
Halo 目前提供了两种分组删除策略:
1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中
1. **删除并将附件移动至未分组**:分组被删将被删除,分组下的附件移动到未分组中
2. **删除并同时删除附件**:先删除下的所有附件后,再删除该分组。
:::warning
当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。
:::
:::warning
当使用 `删除并同时删除附件` 方式时,分组下的所有附件会被同时删除且不可恢复、无法找回,请谨慎进行该操作。
:::
## 上传附件
点击附件列表右上方的 `上传` 按钮即可上传新的附件到 Halo。
:::info
附件会被上传到当前选中的分组中,如果选择的是 `全部` 附件,则附件会被默认上传到 `未分组` 中。
:::
![上传附件](/img/user-guide/attachments/attachment-upload.png)
上传附件时你需要先选择一个存储策略,后续上传的附件将会存储在选中的存储策略中。
你可以点击 `浏览``我的设备` 图标唤起本地文件管理器进行文件选择,也可以直接将文件拖拽到待上传文件区域中。
![上传多个附件](/img/user-guide/attachments/attachment-upload-multiple.png)
如上图所示,你可以同时添加多个文件一次性完成多个附件的上传。
1. **分组选择**:你可以选择需要上传到的分组,为了方便,选择之后会在浏览器记住这个选项。
2. **存储策略选择**:你可以选择需要使用的存储策略,为了方便,选择之后会在浏览器记住这个选项。
3. **上传区域**:同时支持拖拽文件、点击上传区域选择文件、粘贴文件。
## 查看附件
点击附件列表中的某一个附件即可查看该附件的详细信息。
:::info
对于存储策略类型为本地存储的附件,详细信息中的的原始链接生成规则为 `/upload/{存储策略存储路径}/{文件名称}`
:::
![附件详情](/img/user-guide/attachments/attachment-detail.png)
1. **预览区域**:目前支持图片、视频、音频的预览。
2. **链接**目前可以显示并复制链接、HTML 格式代码、Markdown 格式代码。
## 删除附件
附件页面提供两种浏览模式,列表模式和平铺模式
目前有两种删除附件的方式,你可以选中一些附件进行批量删除或者点击指定附件所在行后方的 `···` 更多按钮,对单个附件进行删除操作
在平铺模式下,你可以点击附件缩略图右上角的 `√` 图标选中若干个附件,通过上方的批量操作按钮删除选中的附件。
![批量操作附件](/img/user-guide/attachments/attachment-batch-operate.png)
在列表模式下,你可以点击指定附件所在行后方的 `···` 更多按钮,对附件进行删除操作。
:::warning
附件删除后不可恢复、无法找回,请谨慎进行该操作。
:::
## 移动附件所在分组
## 移动附件
![附件移动](/img/user-guide/attachments/attachment-move.png)
与批量删除操作类似,你可以选中多个附件后在上方的批量操作按钮中选择 `移动` 操作,将所选附件移动到指定的分组中。
:::info
需要注意的是,目前移动附件只支持移动分组,不支持存储策略的移动。
:::

@ -11,18 +11,18 @@ Halo 作为一款好用又强大的开源建站工具,配合上不同的模板
控制台是一个 Halo 站点的后台管理系统,只有具有权限的登录用户才可以正常使用控制台功能。你可以在控制台中管理站点中的文章、页面、附件等各种内容,调整站点使用的主题或各种设置。
:::info
控制台默认地址为 `$HALO_EXTERNAL_URL/console/`。忘记密码请参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
控制台的访问入口为 `/console`。忘记密码请参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
:::
### 界面说明
![控制台界面说明](/img/user-guide/common/控制台界面说明.png)
1. **全局搜索框**:点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框,输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索
2. **侧边导航栏**:对控制台提供的功能进行导航,点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目
3. **用户信息展示及操作**:展示当前登录用户的头像、名称及角色等信息,`···` 中提供更多用户相关操作
4. **功能页面标题** 当前所在的功能页面标题
5. **功能页面操作区域**:当前所在功能页面提供的功能操作按钮
1. **全局搜索框**:点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框,输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索
2. **侧边导航栏**:对控制台提供的功能进行导航,点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目
3. **用户信息展示及操作**:展示当前登录用户的头像、名称及角色等信息,`···` 中提供更多用户相关操作
4. **功能页面标题** 当前所在的功能页面标题
5. **功能页面操作区域**:当前所在功能页面提供的功能操作按钮
6. **功能页面主体** 当前所在功能页面的主体显示区域,显示内容及形式视具体页面功能而定。
## 文章
@ -33,19 +33,11 @@ Halo 作为一款好用又强大的开源建站工具,配合上不同的模板
## 页面
Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`
### 功能页面
功能页面通常由各个插件提供,页面功能及在控制台呈现的内容由具体提供该页面的插件决定。
### 自定义页面
自定义页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
## 分类
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
通过分类可以更好地组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
## 标签
@ -59,14 +51,13 @@ Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`。
包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。
:::info
当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
:::
## 插件
用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。
:::info
当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
目前有两个官方渠道可以获取主题和插件:
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::

@ -1,172 +0,0 @@
---
title: 功能配置
description: 系统功能的相关配置说明
---
## 修改博客地址
很多人在部署完成之后都会惊奇的发现,博客前台居然没有样式?究其原因就是无法获取到静态资源,那么为什么获取不到呢?那就是你的博客地址没有设置正确。
第一步:
登录到后台之后,进入 博客设置 -> 常规设置。
第二步:
修改你的博客地址:
- 如果你没有进行域名解析或者没有配置反向代理,那么博客地址一般为 `http://ip:端口`
- 如果你进行了域名解析且配置了反向代理,但是没有配置 SSL 证书,那么博客地址一般为 `http://域名`
- 如果你进行了域名解析、配置了反向代理、也配置了 SSL 证书,那么博客地址一般为 `https://域名`
说了这么多,就是希望你别把 `http://` 或者 `https://` 搞混了。
另外,需要注意的是,地址尾部不需要 `/`
## 注册 Gravatar
很多人反映评论中自己的头像不显示,其实评论部分调用的头像并不是在个人资料中设置的那个,而是 `Gravatar`。所以这一点怪我,从 Halo 发布至今我都没有说明这个事情。
至于什么是 `Gravatar`,引用 `Gravatar` 官方的说明:`全球公认的头像`。这可不是在吹牛,因为只要接入了 Gravatar 的网站,你在网站上使用在 Gravatar 注册的邮箱之后,都会显示你设置的头像,而不需要额外设置。比较出名的网站有 `GitHub``GitLab``V2EX` 等。所以点击 <https://cn.gravatar.com/> 注册一个吧。
## 设置用户头像/Logo/Favicon
### 头像
第一步:
登录到后台之后,进入 用户 -> 个人资料。
第二步:
点击左侧头像即可选择本地附件中的图片。另外,也支持设置为 `Gravatar` 头像。点击 `使用 Gravatar` 即可。当然,前提是你注册了 `Gravatar` 才行。
### Logo/Favicon
第一步:
登录到后台之后,进入 系统 -> 博客设置。
第二步:
在常规设置中找到 Logo/Favicon 输入框,点击输入框后面的按钮即可调用附件库选择图片。
## SEO 设置
先说说程序本身对 SEO 做的优化:
- 支持 sitemap 站点地图:可访问 /sitemap.xml 或 /sitemap.html
- 全站绝对路径
- 页面静态化
- 支持伪静态1.3.0+
需要自己设置的有:
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> SEO 设置。
第二步:
填写你需要的一些关键词和博客描述,这部分可能需要你了解一定的 SEO 优化技巧。
> 另外,文章和自定义页面都可以自行设置关键词和描述(文章设置的高级设置中)。当然,你也可以不设置,系统为自动取你设置的文章标签为关键词,描述会自动取文章的部分内容。
Q&A
Q我刚发布的文章为啥百度搜索不到呢
A这是一件非常正常的事情建议注册百度的站长工具手动或者自动提交链接。
## SMTP 服务
SMTP 服务,简称发信服务,顾名思义就是用来发邮件的。那么,为什么要设置这个呢?有两个用途:
1. 评论通知,收到评论之后发信通知博主,评论者被回复之后发信通知被评论者。
2. 找回密码。
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> SMTP 设置。
第二步:
勾选 `是否启用`,并配置相关信息:
1. SMTP 地址到邮箱服务商查询。举两个例子QQ 邮箱smtp.qq.com163 邮箱smtp.163.com
2. 发送协议:一般不修改,具体可到邮箱服务商查询。
3. SSL 端口:一般不修改,具体可到邮箱服务商查询。
4. 邮箱账号:你的账号。
5. 邮箱密码:你的密码。
6. 发件人:随意。
第三步:
点击发送测试,填上你可以接收到的邮箱,并填写测试内容,最后点击发送。不出意外就可以发送成功,失败了就检查下配置吧。
Q&A
Q发送失败
A先检查配置是否有误如不知道哪里错误请查看日志。点击左上角 `Halo Dashboard`即可进入开发者选项,点击 `实时日志` 即可看到最近的日志。
Q日志说我授权出错但是我密码明明是对的啊
A部分邮箱所谓的密码并不是你的登陆密码需要去邮箱服务商生成 `授权码`。这个才是你需要填写的。
## 设置统计代码
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> 其他设置。
第二步:
`网站统计平台` 提供给你的一串代码填写到 `统计代码` 即可。
Q&A
Q什么是网站统计平台
A诸如百度统计CNZZGoogle Analytics。可以非常详细的统计你网站的访问情况。
## 找一个合适自己的主题
当你搭建好博客之后,如果你不喜欢默认的主题,那么你可以去 [https://halo.run/themes/](https://halo.run/themes/) 选择你喜欢的主题。在这里主要讲一些注意事项。
### 如何安装?
登录到后台之后,进入 外观 -> 主题,在后下角有一个按钮,点击之后选择 `安装主题`。系统提供的两种安装方式。
1. 第一种,远程拉取。你只需要把主题的 GitHub 地址复制进去点击下载即可。
2. 第二种本地上传你需要将主题安装包releases下载到本地然后选择 `本地上传` 点击选择你下载好的主题即可。
> 一般情况下,推荐第二种,第一种一般安装的为开发版本,建议谨慎使用。
### 设置主题
> 可能有一部分人不太清楚,一般情况下,每个主题都是有单独的设置选项的。
点击主题下方的设置按钮即可进入主题设置。另外主题设置还有一种预览模式,可以实时查看主题设置变更后的效果。当你设置当前激活主题的时候,在页面右下角有一个 `预览模式` 的按钮,点击即可进入预览模式。
## 设置备案信息
由于后台博客设置并没有提供设置备案信息的选项,所以有很多人不知道该怎么添加备案信息,这里简单说明一下。
第一步:
登录到后台之后,进入 系统 -> 博客设置 -> 常规设置。
这时候你应该可以看到一个`页脚信息`的选项,而且有提示 `支持 HTML 格式的文本`。所以我们把备案信息放在这里即可。
第二步:
将整理好的备案信息填写到页脚信息即可,如果没记错的话,公安联网备案是有提供`网站公安机关备案号`和`备案编号HTML代码`的。

@ -9,7 +9,7 @@ description: 使用上的常见问题
### 忘记密码怎么办?
如果安装时没有指定 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量,系统会随机一个初始化密码,可以通过下面的命令进行查看。
如果安装时没有指定 `halo.security.initializer.superadminpassword` 参数,系统会随机一个初始化密码,可以通过下面的命令进行查看。
```bash
docker logs halo | grep 'Generated random password:' | tail -1
@ -25,7 +25,7 @@ docker logs halo | grep 'Generated random password:' | tail -1
docker stop halo
```
2. 连接 Halo 使用的数据库,删除 admin 用户记录
2. 连接 Halo 使用的数据库,删除管理员的用户记录(配置文件中的 `halo.security.initializer.superadminusername`),这里以 `admin` 为例
以容器化部署的 PostgreSQL 为例,假设容器名称为 `halo_db`
@ -49,7 +49,7 @@ docker logs halo | grep 'Generated random password:' | tail -1
4. 登录 Halo 控制台
如果部署时通过 `HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME` 和 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量指定了初始化用户名和密码,使用该用户名密码登录控制台。
如果部署时通过 `halo.security.initializer.superadminusername` 和 `halo.security.initializer.superadminpassword` 参数指定了初始化用户名和密码,使用该用户名密码登录控制台。
如果未指定该配置,则默认用户名为 `admin`,默认密码将打印在 Halo 容器日志中,可以通过如下命令查看。
@ -57,16 +57,6 @@ docker logs halo | grep 'Generated random password:' | tail -1
docker logs halo | grep 'Generated random password:' | tail -1
```
### 为什么百度无法搜索到我的站点?
这是一个暂时无法解答的问题。所涉及到的问题过多,受影响因素可能有域名、服务器 IP 位置、建站时间、网站结构、内容等等。建议了解一下 SEO 相关知识对网站进行优化,目前我们在程序方面做的优化有:
- 支持 sitemap 站点地图:可访问 `/sitemap.xml``/sitemap.html`
- 全站绝对路径
- 页面静态化
- 支持自定义文章关键字和描述
- 支持自定义站点关键字以及站点描述
### 附件上传提示 `413 Request Entity Too Large` 如何解决?
这可能是由于 Nginx 的上传大小限制所导致的。可以在 Nginx 的配置文件下的 server 节点加入 `client_max_body_size 1024m;` 即可解决,如果 1024m 还不够,请自行断定,详细配置参考如下:
@ -110,34 +100,37 @@ server {
-it -d \
--name halo-1 \
-p 8090:8090 \
-v ~/.halo2.1:/root/.halo2 \
-e HALO_EXTERNAL_URL=http://localhost:8090/ \
-e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
halohub/halo:2.6
-v ~/.halo2:/root/.halo2 \
halohub/halo:2.6 \
--halo.external-url=http://localhost:8090/ \
--halo.security.initializer.superadminusername=admin \
--halo.security.initializer.superadminpassword=P@88w0rd
# 第二个 Halo 容器
docker run \
-it -d \
--name halo-2 \
-p 8090:8090 \
-v ~/.halo2.2:/root/.halo2 \
-e HALO_EXTERNAL_URL=http://localhost:8090/ \
-e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
halohub/halo:2.6
-p 8091:8090 \
-v ~/.halo2_2:/root/.halo2 \
halohub/halo:2.6 \
--halo.external-url=http://localhost:8091/ \
--halo.security.initializer.superadminusername=admin \
--halo.security.initializer.superadminpassword=P@88w0rd
```
更多 Docker 相关的教程请参考:[使用 Docker 部署 Halo](../getting-started/install/docker.md)
### 如何查看运行日志?
使用 docker logs 命令进行查看。
1. 可以在 Console 端的概览页面下载最近的日志文件。
2. 使用 docker logs 命令进行查看。
```bash
# '-f' 滚动更新日志
# '-n 200' 从倒数第200行开始查看
# 更多帮助可以查看 'docker logs --help'
docker logs -f halo_next -n 200
```
```bash
# '-f' 滚动更新日志
# '-n 200' 从倒数第200行开始查看
# 更多帮助可以查看 'docker logs --help'
docker logs -f halo -n 200
```
### 前台样式丢失,如何解决?

@ -3,39 +3,18 @@ title: 页面
description: 页面管理相关功能说明
---
Halo 中存在两种类型的页面,`功能页面` 和 `自定义页面`
页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等
### 功能页面
自定义页面的访问链接为 `/{slug}` 其中 `slug` 为自定义页面的别名。
功能页面通常由各个插件提供,页面功能及在控制台呈现的内容由具体提供该页面的插件决定
对于如下的关于页面,便可以通过 `/about` 地址进行访问
例如[链接插件](https://github.com/halo-sigs/plugin-links)便实现了一个站点链接管理功能,用户可以通过该插件更加方便地管理与站点相关的友情链接。安装该插件后,在功能页面会出现列表会出现如下条目。
![链接功能页面](/img/user-guide/pages/page-links.png)
点击这个条目即可进入到链接插件提供的配置管理页面。
![链接功能页面](/img/user-guide/pages/page-links-edit.png)
你可以在这个页面中管理链接分组和链接条目。链接信息维护完成后,通过 `$HALO_EXTERNAL_URL/links/` 便可访问到对应的页面。
:::info
对于 `links` 页面的访问需要主题端支持,即安装使用的主题需要有对应的 `links.html` 模板,且在模板中正确处理链接插件提供的数据。
:::
### 自定义页面
自定义页面与文章类似,同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息,一般用于站点中单一展示功能的页面,例如常见的站点关于页面、联系我们页面等。
自定义页面的访问链接为 `$HALO_EXTERNAL_URL/{slug}/` 其中 `slug` 为自定义页面的别名。
对于如下的关于页面,便可以通过 `$HALO_EXTERNAL_URL/page/` 地址进行访问。
![链接功能页面](/img/user-guide/pages/page-about.png)
:::info
自定义页面默认使用主题端的 `page.html` 模板进行渲染,如果主题中提供了针对自定义页面的其他模板,用户可以通过修改自定义页面高级设置中的自定义模板设置进行使用。
:::
#### 自定义页面操作
#### 页面操作
对于自定义页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南-文章》](./posts.md)章节,此处不再赘述。
对于页面的新建、设置、发布及删除等操作,与文章操作基本一致,具体操作请参考[《用户指南-文章》](./posts.md)章节,此处不再赘述。

@ -5,19 +5,41 @@ description: 插件管理相关功能说明
插件时用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用,可以单独安装、升级、卸载。
本文档仅对插件的基本管理功能进行说明,关于插件的详细使用说明请参考对应插件的文档。
:::info
当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
:::
目前有两个官方渠道可以获取插件:
本文档仅对插件的基本管理功能进行说明,关于插件的详细使用说明请参考对应插件的文档。
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::
## 安装插件
点击插件页面右上角的 `安装` 按钮,在弹出的文件上传对话框中上传插件文件即可完成插件安装。
进入插件管理页面,点击右上角的 `安装` 按钮即可打开插件安装的对话框。
和主题一样,插件同时支持本地上传安装和远程下载安装。
### 本地上传安装
![安装插件](/img/user-guide/plugins/plugin-install.png)
插件安装成功后,便会出现在已安装主题列表中。你可以点击某个插件进入到插件详情页面。
插件安装成功后,便会出现在插件管理的列表中。
### 远程下载安装
同样,在安装插件的对话框中,切换到远程下载选项卡,输入插件的下载地址,点击 `下载` 按钮即可开始下载插件。
插件安装成功后,便会出现在插件管理的列表中。
此外, Halo 的[应用市场](https://halo.run/store/apps)也支持通过输入站点地址的方式自动跳转到你的站点进行安装,演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/install-plugin-from-store.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
:::info
插件安装成功后会提示你是否需要启动该插件,你可以根据需要选择是否启动。
:::
## 插件设置
@ -25,7 +47,7 @@ description: 插件管理相关功能说明
![插件设置](/img/user-guide/plugins/plugin-setting.png)
以 Unsplash 插件为例,该提供仅在基本设置组中提供了 `Access Key` 一项配置,用于调用 Unsplash 接口
此处以 `plugin-umami` 插件为例
:::info
你可以点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `重置` 选项将插件提供的设置项恢复为默认值。
@ -39,11 +61,16 @@ description: 插件管理相关功能说明
## 升级插件
点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `升级` 选项即可上传新的插件文件对当前插件进行升级。
点击具体插件的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级插件的对话框,与安装插件一样,同时支持本地上传和远程下载。
## 重置
如果你需要清空所有插件配置并重新配置插件,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。
## 卸载插件
点击插件列表指定插件所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前插件进行卸载。
![卸载插件](/img/user-guide/plugins/plugin-uninstall.png)
:::info

@ -7,58 +7,52 @@ description: 文章管理相关功能说明
目前你可以通过以下两种方式新建一篇文章:
1. 点击仪表盘快捷访问组件中的创建文章
:::info
仪表盘中需要存在快捷访问组件(默认存在)。关于仪表盘组件配置,请参考《用户指南-仪表盘》章节。
:::
2. 通过左侧导航栏进入文章页面,点击右上角的新建按钮
进入到如下页面后,你就可以开始编辑自己的文章内容了:
![文章编辑界面说明](/img/user-guide/posts/post-edit.png)
在文章编辑器中输入你想展现的内容,你可以通过编辑器上方的工具栏调整指定内容的格式或者插入图片、音视频等各类附件。编辑器还提供了各种快捷指令,通过输入 `/` 字符便可以快速选择常用的输入类型,不需要操作鼠标便可以轻松完成文章排版。
1. **编辑器切换**:如果安装了其他的编辑器插件,那么就可以在这个位置选择所需的编辑器。
2. **预览**:点击预览按钮可以在未发布的时候预览文章的渲染效果。
3. **保存**:仅保存文章内容,但是不发布。
4. **发布**:保存并发布文章内容。
:::info
编辑器详细使用说明请参考[《用户指南-编辑器》](./posts.md)。
Halo 支持通过插件来拓展文章编辑器,目前 Halo 官方维护了另外两款编辑器插件,可以按需安装使用:
如果安装并启用了额外的编辑器插件,可以点击右上角切换使用不同的编辑器。以下文档内容均使用默认编辑器进行说明。
:::
在页面右侧你可以看到文章的大纲结构及字词数等详细信息。一切满意之后,你可以选择暂存这篇文章的草稿或直接将文章进行发布。
:::info
点击保存按钮将只保存文章内容的修改,不会将新修改的内容进行发布。对于未发布的文章内容,只有授权用户可以在控制台进行查看,不会出现在站点内容中;
点击发布按钮将直接发布修改后的内容。对于已发布的文章,默认可以通过站点地址进行公开访问,用户可以在文章高级设置中修改可见性。
1. StackEdit<https://halo.run/store/apps/app-hDXMG>
2. ByteMD<https://halo.run/store/apps/app-HTyhC>
:::
## 文章设置
当你想修改一篇文章的标题、所属分类等信息时,你可以通过以下方式进行操作:
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择设置
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择设置。
2. 在文章列表点击指定文章的标题进入文章编辑页面,点击页面右上角的设置按钮。
![文章编辑界面说明](/img/user-guide/posts/post-setting.png)
### 设置说明
- **标题**:用于在主题端显示的文章标题
- **别名**多用于文章 URL 路径定位,一般不会出现在页面中;
- **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类
- **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签
- **自动生成摘要**:文章摘要是对文章内容的概括性描述
- **是** 系统根据文章内容,自动生成一段摘要文本;
- **标题**:用于在主题端显示的文章标题
- **别名**通常用于生成文章访问地址,如:`/archives/{slug}`。
- **分类目录**:文章所属分类,方便用户区分文章类型进行针对性浏览,一篇文章可以属于多个分类
- **标签**:文章添加的标签,方便用户更进一步标识文章信息,一篇文章可以添加多个标签
- **自动生成摘要**:文章摘要是对文章内容的概括性描述
- **是** 系统根据文章内容,自动生成一段摘要
- **否** 用户自行输入文章摘要文本。
- **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论;
- **是否置顶**:文章是否排序在文章列表的最顶部;
- **可见性**:访问站点主题端时,哪些人可以看到这篇文章;
- **公开**:所有用户均可看到这篇文章,包括未登录用户;
- **自定义摘要**:用户自行输入的文章摘要文本,仅当 `自动生成摘要` 为否时生效。
- **允许评论**:是否允许用户在主题端浏览文章时对该文章发起评论。
- **是否置顶**:文章是否排序在文章列表的最顶部。
- **可见性**:访问站点主题端时,哪些人可以看到这篇文章。
- **公开**:所有用户均可看到这篇文章,包括未登录用户。
- **私有**:仅文章作者可以看到这篇文章。
- **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准
- **自定义模板**主题端使用哪一个文章模板进行页面渲染;
- **封面图**用户在主题端显示的文章封面图,需要主题支持该功能;
- **元数据**:供主题、插件使用的额外数据信息。例如 Halo 官网主题仓库中的主题,便可以使用该功能为主题类型的文章增加一条名为下载地址的元数据,提供对应主题的下载链接
- **发表时间**:手动指定文章的发表时间,未指定时以实际发布时间为准
- **自定义模板**自定义文章的渲染模板,由主题提供支持。
- **封面图**文章封面图设置,需要主题支持该功能。
- **元数据**:供主题、插件使用的额外数据信息。比如主题在文章页面提供了一个下载按钮,那么就可以通过元数据来指定下载地址
## 发布及取消发布
@ -66,13 +60,13 @@ description: 文章管理相关功能说明
你可以在上文介绍的文章设置对话框中,修改文章的发布状态。
在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮;若文章处于未发布状态,下方怎会显示发布按钮。
在文章设置对话框中,若文章当前处于已发布状态,下方会显示取消发布按钮。若文章处于未发布状态,下方则不会显示发布按钮。
## 删除文章
当你不再需要一篇文章时,你可以通过以下方式删除该文章:
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除
1. 点击文章列表指定文章所在行的 `···` 更多操作按钮,选择删除
2. 勾选文章列表中的全选/多选框,选中一篇或多篇文章进行批量删除。
文章删除后会进入回收站中,点击右上角的回收站按钮进入回收站。在回收站中,你可以永久删除或恢复指定的文章。
@ -83,7 +77,7 @@ description: 文章管理相关功能说明
## 文章分类管理
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
通过分类可以更好组织管理文章。分类之间存在层级关系,一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
在文章管理页面,点击页面右上角的 `分类` 按钮即可进入分类管理页面。
@ -95,11 +89,11 @@ description: 文章管理相关功能说明
#### 设置说明
- **名称**:用于在主题端显示的分类名称
- **别名**用于分类 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/categories/{slug}`,其中 `slug` 为分类别名,访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](./settings#主题路由设置)
- **自定义模板**主题端使用哪一个文章分类模板进行页面渲染;
- **封面图**用户在主题端显示的文章分类封面图,需要主题支持该功能;
- **描述**:关于改文章分类的更多描述信息;
- **名称**:用于在主题端显示的分类名称
- **别名**通常用于生成分类归档页面的访问地址。默认路径规则为 `/categories/{slug}`,其中 `slug` 为分类别名,访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](./settings#主题路由设置)
- **自定义模板**自定义分类归档页面的渲染模板,由主题提供支持。
- **封面图**分类封面图设置,需要主题支持该功能。
- **描述**:关于该文章分类的更多描述信息。
- **元数据**:供主题、插件使用的额外数据信息。例如部分主题期望使用不同的颜色对分类进行区分,便可以使用该功能为分类增加颜色相关的元数据。
### 调整分类层级
@ -110,9 +104,10 @@ description: 文章管理相关功能说明
![移动文章分类](/img/user-guide/posts/category-move.gif)
### 修改删除分类
### 修改/删除分类
点击指定分类所在行后方的 `···` 更多操作按钮,可以对文章分类进行修改或删除。
:::warning
文章分类删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。
:::
@ -129,22 +124,16 @@ description: 文章管理相关功能说明
#### 设置说明
- **名称**:用于在主题端显示的标签名称
- **别名**用于标签 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/tags/{slug}`,其中 `slug` 为标签别名,访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](./settings#主题路由设置)
- **颜色**:用于在控制台及主题端显示的标签颜色,主题端显示颜色需要主题支持该功能
- **封面图**用户在主题端显示的标签封面图,需要主题支持该功能;
- **名称**:用于在主题端显示的标签名称
- **别名**通常用于生成标签归档页面的访问地址。默认路径规则为 `/tags/{slug}`,其中 `slug` 为标签别名,访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](./settings#主题路由设置)
- **颜色**:用于在控制台及主题端显示的标签颜色,主题端显示颜色需要主题支持该功能
- **封面图**标签封面图设置,需要主题支持该功能。
- **元数据**:供主题、插件使用的额外数据信息。
### 修改删除标签
标签页面提供两种浏览模式,列表模式和平铺模式。点击右上方红框区域对应模式的切换按钮即可进行切换。
![标签浏览](/img/user-guide/posts/tag-list.png)
### 修改/删除标签
在列表模式下,点击指定标签所在行后方的 `···` 更多操作按钮,可以对文章标签进行修改或删除。
在平铺模式下,直接点击对应的标签,即可对文章标签进行修改。
:::warning
文章标签删除后,对应文章的关联将被解除,且该操作不可恢复,请谨慎进行该操作。
:::

@ -9,8 +9,8 @@ Halo 提供了以下站点基本信息设置:
- **站点标题**
- **站点副标题**
- **站点 Logo 图片**
- **站点 Favion 图片**
- **Logo**
- **Favicon**
在控制台设置完成后,主题端可以通过特定的表达式获取到这些信息并且在对应的位置进行展示。具体是否读取使用这些配置、在哪些位置显示这些信息由使用的不同主题而决定。
@ -27,30 +27,44 @@ Halo 提供了以下站点基本信息设置:
- **分类页文章显示条数**
- **标签页文章显示条数**
## SEO设置
## SEO 设置
针对站点的 SEO搜索引擎优化需求Halo 提供了以下设置项:
- **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="robots" content="noindex" />`
- **站点关键词**:格式为以`,`分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="keywords"> content="{用户的配置关键词}" />`
- **站点描述**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name=""> content="{用户的配置描述}" />`
- **屏蔽搜索引擎**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="robots" content="noindex" />`
- **站点关键词**:格式为以`,`分隔的关键词列表,配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="keywords"> content="{关键词}" />`
:::warning 注意
目前主流的搜索引擎(如 Google、Bing、百度搜索等已经不再使用该标签作为关键词的参考因此该设置项的作用已经不大未来我们也可能会移除该设置项。
:::
- **站点描述**:配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="description" content="{描述}" />`
## 用户设置
- **开放注册**:是否允许访客注册,勾选之后在登录页面会显示注册入口。
- **默认角色**:新注册用户的默认角色。
## 评论设置
针对站点的评论功能Halo 提供了以下设置项:
- **启用评论**:全局评论功能开关配置,修改后影响所有文章、页面的评论功能;
- **新评论审核**:新增的评论是否需要在控制台进行审核,审核通过后其他访问者才能看到该条评论;
- **仅允许注册用户评论**:开启后只有登录用户才能添加评论,关闭后匿名(未登录)访问者也可以添加评论。
- **启用评论**:全局评论功能开关配置,修改后影响所有文章、页面的评论功能
- **新评论审核**:新增的评论是否需要在控制台进行审核,审核通过后其他访问者才能看到该条评论
- **仅允许注册用户评论**:开启后只有登录用户才能添加评论,关闭后匿名(未登录)的访客也可以通过自行填写昵称、邮箱、网址等信息进行评论。
## 主题路由设置
针对访问站点各种类型页面的 URL 生成规则Halo 提供了以下主题路由设置项:
- **分类页路由前缀**:定位到指定文章分类页面的 URL 规则前缀,默认为 `/categories/{文章分类别名}`,修改后为 `/{用户定义的分类页路由前缀/{文章分类别名}`
- **标签页路由前缀**:定位到指定文章标签页面的 URL 规则前缀,默认为 `/tags/{文章标签别名}`,修改后为 `/{用户定义的标签页路由前缀/{文章标签别名}`
- **归档页路由前缀**:定位到文章归档页面的 URL 规则前缀,默认为 `/archives/{年}/{月}` 等路径,修改后为 `/{用户定义的归档页路由前缀/{年}/{月}` 等;
- **文章详情页访问规则**:定位到具体文章详情页面的 URL 规则前缀,默认为 `/archives/{文章别名}` ,用户可从以下路径规则进行选择:
- **分类页路由前缀**:定位到分类列表页面以及分类归档页面。
- 默认的分类列表页面 URL 规则前缀为 `/categories`
- 默认的分类归档页面 URL 规则前缀为 `/categories/{slug}`
- **标签页路由前缀**:定位到标签列表页面以及标签归档页面。
- 默认的标签列表页面 URL 规则前缀为 `/tags`
- 默认的标签归档页面 URL 规则前缀为 `/tags/{slug}`
- **归档页路由前缀**:定位到文章归档页面的 URL 规则前缀,默认为 `/archives`
- **文章详情页访问规则**:定位到具体文章详情页面的 URL 规则前缀,默认为 `/archives/{slug}` ,用户可从以下路径规则进行选择:
- `/archives/{slug}`
- `/archives/{name}`
- `/?p={name}`
@ -59,14 +73,19 @@ Halo 提供了以下站点基本信息设置:
- `/{year}/{slug}`
- `/{year}/{month}/{slug}`
- `/{year}/{month}/{day}/{slug}`
:::info 变量说明
- `slug`:文章别名;
- `name`:文章 `metadata.name` 字段值;
- `year`:四位数格式的文章发布年份;
- `month`:两位数格式的文章发布月份:
- `day`:两位数格式的文章发布日。
:::
:::info 变量说明
- `slug`:文章别名
- `name`:文章 `metadata.name` 字段值
- `year`:四位数格式的文章发布年份
- `month`:两位数格式的文章发布月份
- `day`:两位数格式的文章发布日
:::
## 代码注入
你可以使用代码注入功能,在特定类型的页面中注入额外的代码。你可以通过该功能覆盖或补充部分主题 CSS 样式,或者引入额外的 JavaScript 脚本扩展主题端功能。
- **全局 head 标签**:该代码将会被注入到所有页面的 head 标签中。
- **内容页 head 标签**:该代码将会被注入到文章、页面详情页的 head 标签中。
- **页脚**:该代码将会被注入到所有页面的页脚中。

@ -4,41 +4,50 @@ description: 主题管理相关功能说明
---
主题包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式,由 Halo 管理端所配置使用的主题所决定。
:::info
当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
目前有两个官方渠道可以获取主题:
- 应用市场:<https://halo.run/store/apps>
- Awesome Halo<https://github.com/halo-sigs/awesome-halo>
:::
## 安装主题
点击主题页面右上方的 `主题管理` 按钮即可弹出主题管理对话框。
目前 Halo 提供了两种主题安装方式
目前 Halo 提供了两种主题安装方式
1. 通过控制台上传安装
2. 将主题文件夹拷贝到服务器上的 `{Halo 工作目录}/themes/` 目录下等待 Halo 自动扫描
### 本地上传安装
针对第一种安装方式,你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的文件上传对话框中上传主题压缩包。
你可以点击主题管理对话框下方的 `安装主题` 按钮,在弹出的安装主题对话框中上传主题压缩包。
![安装主题](/img/user-guide/themes/theme-install.png)
主题安装成功后,便会出现在已安装主题列表中。
针对第二种方式,你需要手动将解压后的主题文件夹拷贝到服务器上的指定目录下,如果主题校验通过,你便可以在主题列表的 `未安装` 标签页中看到该主题。
### 远程下载安装
同样,在安装主题的对话框中,切换到远程下载选项卡,输入主题的下载地址,点击 `下载` 按钮即可开始下载主题。
之后点击主题所在行后方的 `安装` 按钮,即可完成该主题的安装。
下载完成后,便会出现在已安装主题列表中
![后台安装主题](/img/user-guide/themes/theme-install-alt.png)
此外, Halo 的[应用市场](https://halo.run/store/apps)也支持通过输入站点地址的方式自动跳转到你的站点进行安装,演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/install-theme-from-store.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 切换主题
同样点击主题页面右上方的 `主题管理` 按钮弹出主题管理对话框。
在弹框中点击选中要切换的目标主题,此时页面返回到主题详情页,点击右上角的 `启用` 按钮即可将当前主题切换为实际使用的主题。
:::info
仅选中主题不点击右上角的 `启用` 按钮时,不会影响当前实际使用的主题。
:::
你也可以在已安装主题列表中,通过后方 ··· 的更多操作中的启用选项直接启用指定的主题。
你也可以在已安装主题列表中,通过后方 `···` 的更多操作中的启用选项直接启用指定的主题。
## 修改主题设置
@ -56,18 +65,25 @@ description: 主题管理相关功能说明
通过预览功能,你可以在不更改当前启用主题的情况下查看不同主题的效果。点击主题详情页面右上角的 `预览` 按钮预览当前主题,或者进入已安装主题列表,通过后方 `···` 的更多操作中的预览选项预览指定的主题。
![主题设置](/img/user-guide/themes/theme-preview.png)
在主题预览页面你可以切换不同分辨率的设备,模拟主题在不同终端下的显示效果。也可以通过右上角的功能菜单切换预览的主题,或者调整当前主题的设置,查看不同设置下主题所展现的区别。
演示视频:
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/theme-preview.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 升级主题
点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可上传新的主题包对当前主题进行升级更新。
点击主题详情页右上角的 `···` 更多操作按钮,选择其中的 `升级` 选项即可打开升级主题的对话框,与安装主题一样,同时支持本地上传和远程下载
## 重载主题配置
如果当前主题提供的设置项发生变化,可以通过 `···` 更多操作中的 `重载主题配置` 选项对主题配置项进行更新。
## 重置
如果你需要清空所有主题配置并重新配置主题,你可以通过 `···` 更多操作中的 `重置` 选项将主题提供的设置项恢复为默认值。
## 卸载主题
进入已安装主题列表,点击指定主题所在行后方的 `···` 更多操作按钮,选择其中的 `卸载` 选项即可对当前主题进行卸载。

@ -7,10 +7,6 @@ description: 用户管理、权限配置相关功能说明
Halo 2.0 版本采用了基于角色的权限控制RBAC体系。不同于之前 1.x 版本的单用户设计,现在你可以创建多个用户并且通过赋予不同用户不同角色的方式,为他们分配不同的权限。
Halo 中的权限控制体系示例:
![权限控制体系示例](/img/user-guide/user-permission.png)
## 用户
点击左侧导航栏的 `用户` 条目进入用户管理页面。
@ -93,3 +89,23 @@ Halo 提供了全新创建和基于已有角色创建两种角色创建方式。
:::warning
删除角色后,分配了该角色的用户会丧失对应的权限,影响用户使用。此操作不可恢复。
:::
## 身份认证
目前 Halo 默认仅支持本地身份认证,但可以通过插件的方式拓展其他三方的身份认证方式。
:::info
目前 Halo 官方提供的身份认证插件:
- OAuth2 认证:<https://halo.run/store/apps/app-ESVDK>
:::
你可以在用户管理界面的右上角点击 `身份认证` 按钮,进入身份认证管理页面。
![身份认证](/img/user-guide/users/auth-providers-entry.png)
进入身份认证管理页面之后,如果你已经安装了提供身份认证方式的插件,你就可以在列表中看到对应的身份认证方式,你可以对其进行设置并启用。
![身份认证方式](/img/user-guide/users/auth-providers.png)
> 这里是安装了 [OAuth2 认证](https://halo.run/store/apps/app-ESVDK) 插件,提供了 `GitHub`、`GitLab`、`Gitee` 三种 OAuth2 认证方式。

Loading…
Cancel
Save