版本：5.1

本文档

本 Joomla 开发手册使用 Docusaurus 3 构建，Docusaurus 3 是一个现代静态网站生成器。如果您想为它做出贡献，本页将帮助您入门。

文档更新通过 Joomla 手册 github 仓库进行管理，因此您应该首先将此仓库分叉到您自己的 github 帐户中。然后，您可以更改文档文件并向 Joomla 手册提交拉取请求。确保您继续将您的分叉分支与 Joomla 手册的 main 分支同步。

该文档使用 Markdown 语法，并添加了 Docusaurus 提供的额外功能。

要更改文档，您可能发现使用以下两个选项之一最容易

在您自己的机器上安装 Docusaurus，并在那里进行更改
使用 github dev 在 github 服务器上进行更改。

安装 Docusaurus

要在您自己的机器上安装 Docusaurus，您应该初始化一个本地 git 仓库，并将手动从您在 githut 仓库中分叉的副本克隆到此 git 实例中。

然后，更改目录到您的本地 git 仓库并发出以下命令

$ npm install

安装 Docusaurus 后

$ npm run start

此命令启动一个本地开发服务器并打开一个浏览器窗口。大多数更改都会实时反映出来，无需重新启动服务器。

$ npm run build

此命令将静态内容生成到 build 目录中，可以使用任何静态内容托管服务进行服务。

使用 github dev

要使用 github dev，请转到您的仓库并按“.”（点）键，如 github.dev 指南中所述。然后，您可以

为您的更改创建新的 git 分支
创建新文件和文件夹，修改和删除现有文件，上传文件
预览文件（右键单击文件选项卡） - 这将显示解释的 markdown，但不会解释 Docusaurus 添加的内容
提交并推送更改
返回 github 仓库（单击左下角的 GitHub，或在 URL 中将 github.dev 替换为 github.com）

拉取请求

在您向 Joomla 手册提交拉取请求后，将运行测试构建以识别文档中的任何问题。如果您发现某个检查失败，请单击失败检查的详细信息，然后检查控制台日志以查找问题。

构建成功后，您可以通过导航到类似 http://pr-240.manual.joomlacode.org/docs/ 的 URL 来查看文档更改的结果，其中您将 240 替换为您的拉取请求号。此链接将添加到拉取请求的“检查”部分作为“预览”。

版本

Joomla 手册包含 Joomla 软件多个版本的文档。

github 手册和实时手册之间的版本映射如下

github 手册（开发）	实时 Docusaurus 手册
/docs	“即将发布”版本（在 URL 中显示为 /docs/next）
/versioned_docs/version-m.n	版本 m.n（在“当前版本”下）

如果您的文档更改与多个版本的 Joomla 相关，则您应该将这些更改复制到多个版本的 Joomla 手册中。目前同意更新的版本为

最新完整 Joomla 版本的版本 m.n（“最新”版本）
下一个 Joomla 版本的版本 m.n+1（“即将发布”版本）
Joomla 上一个主要版本的最后一个版本 (m-1.last)

/versioned_docs 中可能存在其他版本，但不会使用更改进行更新，即使文档对这些 Joomla 版本有效。

为了最大程度地减少更改，建议您最初只在 /docs 区域内进行更改，然后提交拉取请求。这允许团队成员查看文档，并允许您修复任何问题，而无需将更改复制到多个版本。然后，在审查过程完成后，可以在合并之前将更改复制到其他版本。

拉取请求合并后，您可以删除您自己仓库中的分支，并将您的 main 分支与更新的 Joomla 手册 main 分支同步。

常见构建问题

如果在文本中使用尖括号或花括号，请始终将它们包含在反引号中，例如 <h1> 或 {['a':1, 'b':2]}。

不要在标题中使用冒号 (:)。

不要使用 <br> 强制换行（例如，在表格文本中）；请改用 <br/>。

Docusaurus 添加的内容

前置内容应用于标题和左侧边栏中的位置

---
title: Best Practices
sidebar-position: 2
---

代码块括在 3 个反引号中，并且可以有标题

hello.php
public static function hello() 
{
    echo "Hello!"; 
}

还支持行号和对单个行的突出显示。

为了提高 markdown 的可读性，请在代码块前后留下一行空白。

警示我们不使用内容周围的空白行，并且在文本消息之前添加 2 个空格。

:::note[Developer Note]
  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::note[Joomla Issue]
  For issues that affect the documentation - please link to the issue on the Joomla Issue Tracker
:::

:::tip
  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::info
  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::warning
  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::danger
  Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

请使用以下占位符来表示文档中未完成的部分。

:::note[TODO]
  This section is missing, please use the **Edit this Page** link at the bottom of this page to add this section.
:::

如果页面尚未完成且缺少大部分内容，请使用

:::caution[TODO]
  This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
:::

图表

在可能的情况下，请使用 Mermaid 创建要包含在文档中的图表。如果 Mermaid 没有提供您需要的内容，请在图像文件之外包含从您的绘图工具中保存的图表。

图像、代码 zip 文件等应保存在文档中使用它们的点的 _assets 文件夹中。

其他建议

为了符合无障碍方面的 a11y 要求，请不要在页面中包含多个级别 1 标题

# Just One H1

安装 Docusaurus​

使用 github dev​

拉取请求​

版本​

常见构建问题​

Docusaurus 添加的内容​

图表​

其他建议​