halo-dev / docs

The open-source repo for docs.halo.run

The open-source repo for docs.halo.run

This website is built using Docusaurus 2, a modern static website generator.

Installation

$ pnpm install 

If you don’t have pnpm installed, you can install it with the following command:

npm install -g pnpm

Local Development

$ pnpm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

$ pnpm build

This command generates static content into the build directory and can be served using any static contents hosting service.

docs's Issues

提供自编译可执行 Jar 和 Docker 镜像的文档

如题，目前我们计划 2.0 不再提供发行版的可执行 Jar。所以期望提供自编译的文档。

主题模版变量获取树结构的文章分类列表

你当前使用的版本

No response

描述一下此特性

参考获取多级菜单的标签，使用<@categoryTag method="tree"> 标签可以成功获取到树结构的文章分类列表但文档中没有提及。建议补充文档说明。

附加信息

No response

开发环境运行的文档需要添加设置初始管理员用户名和密码的提示

目前在开发环境运行的文档中虽然要求了使用 dev 的配置文件运行，但是开发者如果不看配置文件，那么是不知道用户名和密码的，所以可以添加一个提示。

文档：添加默认管理员用户名和密码的环境变量修改

涉及版本2.1、2.2
修改前：

docker run \
  -it -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:2.1 \
  --halo.external-url=http://localhost:8090/ \
  --halo.security.initializer.superadminuser=admin \
  --halo.security.initializer.superadminpassword=P@88w0rd

修改后：

docker run \
  -it -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:2.1 \
  --halo.external-url=http://localhost:8090/ \
  --halo.security.initializer.superadminusername=admin \
  --halo.security.initializer.superadminpassword=P@88w0rd

提供维护者准则文档

建议提供一个维护者准则文档，用于向社区透明 Halo 开源的运作方式，包括但不限于：

1. 版本发布流程相关，比如版本发布节奏，版本维护周期。
2. 依赖更新，比如 patch 版本非特定情况不允许更新依赖。
3. PR 提交相关。
4. 开源社区维护相关。

添加常见问题列表

RT

Netlify 支持 pnpm 包管理器。

参考：https://github.com/halo-dev/halo-admin/blob/master/netlify.toml

提供从 1.x 迁移到 2.0 的文档

如题，我们需要在 2.0 发布之前，提供从 1.x 迁移到 2.0 的文档。

https://github.com/halo-sigs/plugin-migrate

建议将外部地址配置方式更改为配置文件中进行配置

外部地址大概率会在博客搭建好后修改，且修改频次大多情况下只有 1 次。

为了让用户不因为修改外部地址而修改命令或重建容器，建议将此设置的配置方式优化为配置文件（application.yaml）。这样用户只需要重启一下即可生效。

/kind improvement

常见问题列表添加附件/图片无法访问的常见可能性

比如：

• halo-dev/halo#1777
• halo-dev/halo#1676
• Nginx 配置相关

修改开发者指南中 Clone 项目的方式。

目前为：

git clone https://github.com/halo-dev/halo

// 如果你在 Github 上已经添加了你的 ssh key，请使用以下命令进行 clone：
git clone [email protected]:halo-dev/halo.git

git submodule init

git submodule update

建议修改为：

git clone --recursive [email protected]:halo-dev/halo.git

代码贡献部分的文档需要更新

https://docs.halo.run/contribution/pr

拉取代码部分还是使用的 master 分支。

/kind documentation

Docker 文档需要说明 Java opts 参数添加方式。

https://bbs.halo.run/d/1956-docker-xmx

文档多版本管理

鉴于即将发布的 Halo 1.5 的文档可能与 1.4.x 有差异，所以考虑配置多版本文档。参考：https://docusaurus.io/docs/docs-multi-instance

为 Halo 2.0 提供主题开发文档。

如题，我们需要为 Halo 2.0 提供主题的开发文档。稍后我会将基本的大纲列在下方评论。

/kind documentation

主题开发文档中，ContributorFinder 的用法示例有误。

请看：https://docs.halo.run/developer-guide/theme/finder-apis/contributor

方法名叫做 getContributor，但示例里面写的是 ${contributorFinder.getByName('contributor-foo')}

/cc @guqing

这里为什么是叫 getContributor，而不是 getByName 呢？

优化 Docker 容器创建时的配置方式

现在 Halo 已经支持了通过参数来配置应用，请参考：halo-dev/halo#3098

期望文档也与这种方式保持一致。

/kind improvement
/kind documentation

主题开发-导航菜单内缺少关于 target 的字段及描述

see halo-dev/halo#3072

/assign

同步 halo-dev/halo 的 CONTRIBUTING.md

同步 https://github.com/halo-dev/halo/blob/913002d56d64b7dbd20b169921754a12790fcf80/CONTRIBUTING.md

See halo-dev/halo#1888 for more.

/kind documentation
/assign @JohnNiang

添加作者页面的模板路由文档

请参考：halo-dev/halo#2923

/kind documentation

请求添加手动备份和恢复文档

请参考：halo-dev/halo#3274 (comment)。

开发文档的代码风格部分需要标注 checkstyle 的版本。

https://bbs.halo.run/d/2062-idea2021-checkstyle-scope

halo-dev/halo#1470 (comment)

提供通过 Helm Chart 部署的文档

请看：https://github.com/halo-sigs/charts

文档更新

你当前使用的版本

1.5.4

描述一下此特性

文档版本 2.2， 这个提示建议删掉，每次看到这个提示，都感觉官方不建议升到 2.0+ .......

附加信息

为 Halo 2.0 提供插件开发的文档

目前 Halo 2.0 已经支持了插件机制，期望为插件开发编写文档。

/kind documentation

重写开发者文档。

RT

添加使用 MariaDB 的文档

目前 Halo 已经合并了支持原生 MariaDB 驱动的 PR，需要对应修改文档。

halo-dev/halo#2787

补充关于自定义 Thymeleaf 标签的主题开发文档

目前 Halo 提供了 <halo:comment /> 和 <halo:footer /> 标签，但没有相关文档。

使用tencentCloudBase无法部署

在使用tencentCloudBase部署时，因为项目模板是在github上面，代码会拉不下来，请求一直超时导致部署失败；

所以只好将GitHub的代码clone下来，放到gitee，修改为gitee的地址后正常才可以正常部署。

希望官方文档能够更新一下

添加异常页面的主题开发文档

请参考：halo-dev/halo#2925

/kind documentation

添加 1.5.0 Redis 缓存配置的文档。

RT

添加更新 Halo 2.x 的文档

目前，我们仅提供了用 Docker 或 Docker Compose 安装 Halo 2.0 的文档，但是还缺少如何更新 Halo 2.x 的文档。

参考：

• https://bbs.halo.run/d/3095-20%E5%8D%87%E7%BA%A7%E9%95%9C%E5%83%8F%E5%92%8C1x%E7%9A%84%E4%B8%80%E6%A0%B7%E5%90%97

更新宝塔面板的教程

目前宝塔面板已经支持部署托管 Java 应用。

主题开发文档中关于文章和自定义页面的 VO 描述需要添加 lastModifyTime 字段

主题开发文档中关于文章和自定义页面的 VO 描述需要添加 lastModifyTime 字段

halo-dev/halo#3101

/kind documentation

图库根据分组获取图片（listByTeam）示例错误

错误位置

图库#根据分组获取图片（listbyteam）

错误描述

method listByTeam 示例为 listTeams，并且示例中遍历时使用team对象进行遍历

用户指南中插件卸载的配图有误

https://docs.halo.run/user-guide/plugins#%E5%8D%B8%E8%BD%BD%E6%8F%92%E4%BB%B6

/kind documentation

提供 Annotations 表单定义的开发文档。

Halo 2.1.0 即将支持自定义资源的 Annotations，所以需要为主题和插件开发提供定义 Annotations 表单的文档。

/kind documentation

• halo-dev/console#770
• halo-dev/halo#3028

建议提供宝塔docker创建容器的相关配置说明

你当前使用的版本

版本：1.4.17 数据库：MySQL 5.7.18-txsql-log 运行模式：production User Agent：Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36 Edg/97.0.1072.76

描述一下此特性

宝塔自带的docker管理器当中，可以通过图形化界面创建容器，但是halo的官网上没有相关的文档，只有命令行配置文档，但是命令行配置的文档，无法配置容器的运行内存大小，图形化配置当中可以配置运行内存，希望能够提供相关的配置说明。谢谢！

附加信息

补充关于全局变量的主题开发文档

目前 Halo 为主题提供了如 site 的全局变量，但目前没有相关文档，期望补充。

/kind documentation

迁移插件（plugin-migrate）已经更新，需要同时修改使用文档。

如题。

/kind documentation

在贡献文档或者开发者文档提供 prow 的说明。

类似于 https://book.prow.tidb.io/#/

/kind documentation
/cc @halo-dev/sig-docs

文档中的部分模板变量不包含感叹号，询问一下规则。

比如在这个案例中，同一行的模板变量有的带！有的不带，在我具体使用的时候似乎有时候不写！会报错但我没有多留意测试，默认全都加上！了，询问一下这里的具体规则。

添加版本发布规则

发布周期，各版本之间区别等等。

目前无法在 ARM 架构下正常运行 MySQL

请参考：halo-dev/halo#2880 (comment)

/kind bug
/kind documentation

为 Halo 2.0 提供使用文档

如题，我们需要为 Halo 2.0 编写各个特性的使用文档。

建议移除 2.x 文档中的三方指南

目前所有的三方指南的内容都已经过时，建议暂时移除掉过时的链接。请参考：https://docs.halo.run/getting-started/install/third-party。

为主题 API 提供的 VO 添加字段描述。

如题，目前在主题开发文档中，是没有提供 VO 类型定义中字段的解释的，如 https://docs.halo.run/2.0.0-SNAPSHOT/developer-guide/theme/template-variables/index_#%E7%B1%BB%E5%9E%8B%E5%AE%9A%E4%B9%89

期望添加补充。

提供 Docker + MySQL 的部署方案。

RT

更新适配 2.1 版本的文档

将过时文档移除，或改为由 netlify 托管。

参考：https://docusaurus.io/versions

/assign
/kind documentation