add-academy-contribute-guid

zihanKuang · zihanKuang · commit c8198ea17117 · 2025-07-28T11:54:19.000Z
Signed-off-by: ZihanKuang &lt;zihan_kuang@outlook.com&gt;
diff --git a/content/en/cloud/academy/advanced-contribution-guide/index.md b/content/en/cloud/academy/advanced-contribution-guide/index.md
@@ -1,145 +1,118 @@
-### (文档三) Academy 平台架构与高级贡献指南
+---
+title: "Advanced Contributor Guide"
+weight: 4
+description: >
+  An advanced guide to the Layer5 Academy architecture, multi-repository workflow, and development best practices for platform contributors.
+categories: [Academy]
+---
 
-**目标读者**: 希望深入了解 Academy 平台工作原理、需要修改主题或维护整个构建流程的高级贡献者和开发者。
+This guide explores the multi-repository architecture, explains the role of each core component, and provides practical workflows for theme development, local testing, and end-to-end validation with Layer5 Cloud.
 
-**文档目的**: 本文档旨在揭开 Layer5 Academy 平台的多仓库协作模式，详细解释每个核心仓库的职责，并提供进行端到端测试和高级开发的实践指南。
+## The Multi-Repository Model
 
-### **1.0 引言 (Introduction)**
+The [Layer5 Academy platform](https://cloud.layer5.io/academy) is built on a "separation of concerns" architecture. Instead of a single monolithic repository, we use a multi-repository model where content, presentation (theme), and build configurations are managed independently. This approach keeps the system modular, simplifies maintenance, and allows teams to work on different parts of the platform concurrently.
 
-  * **1.1 为什么需要这篇指南?**
-      * 简要说明，与面向内容创作者的《创建你的第一个学习路径》不同，本指南服务于希望理解和改进平台本身的开发者。
+At a high level, the `academy-theme` provides the visual style for content from repositories like `academy-example`, and the `academy-build` repository acts as the central factory, assembling everything into the final website.
 
-### **2.0 宏观视角：系统架构 (The Big Picture: System Architecture)**
+> [layer5-academy](https://github.com/layer5io/layer5-academy) repository hosts all official learning paths and courses published by Layer5. It serves as a feature-complete reference. 
 
-  * **2.1 多仓库协作模型**
-      * 解释 Academy 平台采用的是一种“关注点分离”的架构模式。内容、主题、示例和构建是分开的，以实现更好的模块化和可维护性。
-      * **（建议此处用一张架构图，清晰地展示四个仓库和数据流向）**
-      * **数据流向描述**:
-          * `academy-theme` (主题) 定义了所有内容的“外观”。
-          * `academy-example` (示例) 和 `layer5-academy` (实际内容) 提供了“内容”。
-          * `academy-build` (构建) 是一个“中央工厂”，它拉取指定版本的主题和所有内容模块，将它们“组装”成最终的、可发布的网站。
+## A Deep Dive into the Core Repositories
 
+The Layer5 Academy platform is composed of several core repositories, each with a distinct purpose.
 
-### **3.0 核心仓库详解 (A Deep Dive into the Core Repositories)**
+### [academy-theme](https://github.com/layer5io/academy-theme)
 
-  * **3.1 `academy-theme` (主题仓库：外观与风格)** https://github.com/layer5io/academy-theme
+This repository is the "skin" for the entire Academy. It controls the website's design, including all the layouts, colors, and fonts.
 
-      * **职责**:
-          * 提供所有 Academy 内容的 HTML 布局、CSS 样式。
-          * 定义 Shortcodes、Partials 等可复用组件。
-          * 是所有 Academy 站点的“皮肤”和“骨架”。
-      * **谁会用到**: 前端开发者、UI/UX 设计师、需要修改平台底层功能的开发者。
+### [academy-example](https://github.com/layer5io/academy-example)
 
-  * **3.2 `academy-example` (示例仓库：快速入门模板)** https://github.com/layer5io/academy-example
+This is the "starter kit" for anyone new to creating Academy content. It provides a pre-configured site that new organizations can fork to get started quickly.
 
-      * **职责**:
-          * 作为新组织或新内容创作者的“脚手架”或“模板”。
-          * 提供一个预先配置好的、最小化的、可运行的 Academy 站点。
-          * 是《创建你的第一个学习路径》教程中用户 Fork 和 Clone 的对象。
-      * **谁会用到**: 首次接触 Academy 平台的内容创作者。
+> [Learn How](../cloud/academy/creating-your-learning-path/index.md) to create your own learning path
 
-  * **3.3 `layer5-academy` (官方内容仓库：最佳实践)** https://github.com/layer5io/layer5-academy
+The workflow in this repository is designed to act as a "gatekeeper" for new content. When you create a new GitHub Release, it triggers the following process:
 
-      * **职责**:
-          * 存放 Layer5 官方发布的所有内容和课程。
-          * 作为 `academy-example` 的一个“生产级”和“功能完整”的参照范例。
-          * 展示了如何组织复杂的、多课程的学习路径。
-      * **谁会用到**: 希望参考 Layer5 官方内容组织方式的开发者和内容创作者。
+1. **Sanity Check**: It first runs a local build to ensure the new content has no fundamental errors that would break the site.
 
-  * **3.4 `academy-build` (构建仓库：中央装配工厂)** https://github.com/layer5io/academy-build
+2. **Publishing Notification**: If the check passes, it calls a reusable action from the `academy-build` repository. This action securely sends a request to the Layer5 Cloud API, using your configured `ACADEMY_ORG_ID` and `ACADEMY_TOKEN` secrets.
 
-      * **职责**:
-          * **这是最重要的中央枢纽。**
-          * 包含用于**生产环境构建**的主要 Hugo 配置 (`hugo.yaml`)。
-          * 通过 Go Modules 机制，引用并管理所有独立的内容模块（如 `layer5-academy`, `exoscale-academy` 等）和 `academy-theme` 的版本。
-          * 执行最终的 Hugo 构建命令，生成完整的静态网站。
-      * **谁会用到**: 平台维护者、需要进行端到端测试的开发者。
+{{< alert type="info" title="Publishing Trigger" >}}
+This request effectively says: "A new version of content is ready for this organization. Please update it." This workflow does not build the final site; it only validates the content and notifies the build system.
+{{< /alert >}}
 
+### [academy-build](https://github.com/layer5io/academy-build)
 
-### **4.0 开发者工作流：实践指南 (Developer Workflows: A Practical Guide)**
+**This is the central hub of the entire system.** It contains the main Hugo configuration for the production build and uses Go Modules to manage the versions of all content modules and the `academy-theme`.
 
-如何开发和测试 Academy 主题 (How to Develop and Test the Academy Theme)
+This repository is the **"assembly factory"** and the central hub of the entire system. It holds the master plan for building the final website.
 
-      * 当您需要修改 `academy-theme` 仓库中的代码（例如，更改 CSS 或布局）并希望在完整的 `academy-build` 环境中预览这些更改时，您需要使用 `go mod replace` 指令。
-      * **步骤 1: 修改主题**
-          * 在你的本地 `academy-theme` 仓库副本中进行代码修改，clone任意一个内容仓库，用来运行查看效果
-      * **步骤 2: 在 `academy-build` 中重定向依赖**
-          * 在 `academy-build` 仓库的 `go.mod` 文件中，添加一行 `replace` 指令，将远程的主题仓库地址指向你本地的 `academy-theme` 文件夹。
-        <!-- end list -->
-        ```go
-        // go.mod in academy-build repo
+When triggered, its automated process acts like a master assembly line:
 
-        replace github.com/layer5io/academy-theme => /path/to/your/local/academy-theme (eg.replace github.com/layer5io/academy-theme => ../academy-theme 如果theme和内容仓库是在同一个文件夹下面的话)
-        ```
+1.  **Collects Parts**: It begins by gathering all the necessary components—`academy-theme` and all the course content from the various content repositories.
 
-如果你想在内容文件上简单快速的预览，采用make site
-步骤如下
-1.运行go mod tidy
-2.运行make setup
-3.运行make site
-然后从网页1313：academy进去
+2.  **Assembles the Website**: Next, it combines everything. It applies the theme's design to all the course content, building a single, complete website.
 
-如果你想在cloud stading环境上面预览：
+3.  **Deploys Online**: Finally, it takes the newly built website and automatically pushes it to the cloud platform, making the updates live for everyone to see.
 
-  * **4.2 如何对完整的 Academy 站点进行端到端测试 (Complete Testing of Academy with Cloud)**
+{{< alert type="info" title="Deployment Complete" >}}
+This final push to the meshery-cloud master branch is what makes the updated Academy site go live.
+{{< /alert >}}
 
-      * 所有 Academy 的主要开发和配置都在 `academy-build` 仓库中进行。此仓库包含用于生产构建的主要 Hugo 配置，以及对所有独立 Academy 模块（例如，`layer5`, `exoscale` 等）的引用。
+## Developer Workflows
 
-      * `academy-build` 仓库应作为测试和构建整个 Academy 站点的中央枢纽。
+### When to Use Local Development and Previewing
 
-      * **步骤 1: 在本地构建 Academy**
+Use these workflows for rapid development and iteration on your local machine.
 
-          * 要完整地在本地构建整个 Academy 站点，请运行：
+#### How to Preview Content Changes
 
-        <!-- end list -->
+If you're only changing Markdown files and want a fast preview loop, run these commands from within a content repository (such as `academy-example`):
 
-        ```bash
-        make academy-dev
-        ```
+1. `go mod tidy`: Cleans up and verifies Go module dependencies.
+2. `make setup`: Installs necessary tools and modules defined in the `Makefile`.
+3. `make site`: Starts the local Hugo development server.
 
-      * **步骤 2: 与 Cloud 环境同步**
+You can then view your content by navigating to `http://localhost:1313/academy`.
 
-          * 构建完成后，您可以通过运行以下命令将生成的 HTML 文件与 Cloud 同步：
+#### How to Develop the Academy Theme
 
-        <!-- end list -->
+When you need to modify the `academy-theme` and see its effect on real content, you'll use the `go mod replace` directive:
 
-        ```bash
-        make sync-with-cloud
-        ```
+1. **Modify the Theme**: Make your code changes in your local clone of the `academy-theme` repository.
+2. **Redirect the Dependency**: In the `go.mod` file of the content repository you're using for previewing (e.g., `academy-example`), add a `replace` directive to point Hugo to your local theme directory:
+   ```go
+   replace github.com/layer5io/academy-theme => ../academy-theme
+   ```
+3. **Relaunch the Server**: Run `make site` again. The local server will now use your local theme code, allowing you to see your changes instantly.
 
-      * **步骤 3: 预览**
+### When to Use End-to-End Testing with Layer5 Cloud
 
-          * 同步后，您可以访问托管在 Cloud 上的 Academy 页面以查看最新的内容。大概十分钟
+The previous steps are the same: use the replace directive in your `go.mod` file to point to the local version of either the example or the theme repository, depending on what you want to test.
 
-如果你想更快的查看内容，可以运行
- one way of holistically testing changes is to build the academy-build ( make academy-prod ) and test the changes
- 去查看生成的html文件，也是可以用来查看问题的，并且可以观察到底是xx
+Use this workflow to ensure your changes work correctly within the final Layer5 Cloud environment:
 
- 好的，根据我们完整的对话内容，我为你提炼了几个可以直接补充到你现有贡献指南中的核心知识点。这些内容都是基于我们一起解决问题的过程得出的，可以极大地帮助后续的开发者。
+1. **Build Locally**: From the root of the `academy-build` repository, run the command to build the entire Academy site. This fetches all remote content modules and the theme:
+   ```bash
+   make academy-dev
+   ```
+2. **Sync with Cloud**: After the build completes, run the following command to sync the generated static files with the Layer5 Cloud staging environment:
+   ```bash
+   make sync-with-cloud
+   ```
+3. **Preview on Staging**: Your changes will be available on the [staging environment](https://staging-cloud.layer5.io/) within approximately 10 minutes.
 
-建议补充内容
-1. (建议加入 2.0 系统架构 章节) 核心渲染机制：Hugo 生成 JSON，前端动态加载
-Academy 平台并非传统的纯静态 HTML 网站。它的核心是一种“半静态半动态”的渲染机制，理解这一点对于调试至关重要。
+{{< alert type="warning" title="Local vs. Cloud Discrepancies" >}}
+The local preview (`make site`) is excellent for rapid development, but it is **not** a 100% accurate representation of the final product. The Cloud UI acts as a wrapper around the Academy content, which can introduce subtle differences. These are often caused by CSS class conflicts or variations in JavaScript execution within the larger application.
 
-工作流程:
+**Always verify your changes in the staging environment before considering them complete.**
+{{< /alert >}}
 
-构建时 (Build Time): 当运行 make 命令时，Hugo 会执行。它会使用 layouts/ 目录下的特殊模板（例如 list.json.json）来遍历所有内容文件。
+### When to Use a Holistic Build Test
 
-生成数据: Hugo 不会直接生成复杂的 HTML 页面，而是将所有学习路径和课程的数据聚合成一个或多个 JSON 文件（例如 public/learning-paths/index.json）。这个 JSON 文件相当于一个为前端准备的 “API 数据源”。
+If you need a faster way to check the final output without syncing to the cloud, you can run a production-like build locally from the `academy-build` repo:
 
-运行时 (Run Time): 用户的浏览器加载一个相对简单的 HTML“外壳”页面。
+```bash
+make academy-prod
+```
 
-动态渲染: 页面中的 JavaScript 脚本会发起请求，获取并读取之前生成的 JSON 文件，然后根据这份数据动态地在浏览器中创建和渲染出用户看到的课程卡片列表。
-
-对开发者的启示:
-
-当你修改了内容或主题，发现页面显示不正确时，首要的调试步骤通常是去检查 public 目录下生成的那个 .json 文件，确认里面的数据（特别是 banner URL、title 等）是否符合预期。
-
-很多问题（比如路径错误、格式问题）都可以在这个中间产物（JSON 文件）中被快速定位。
-
-
- 注意！theme里面的主题不是百分百到cloud上面的！大部分是，但是少数会存在不一样，因为cloud包裹xxx的原因，所以尽管可以采用make site快速开发，也要在提交前查看stading env的效果
-
- 清理的步骤！怎么清理，删除？go mod tidy？
- make clean？
- 删除public？
+This command generates the final static files in the `public/` directory. You can inspect the generated HTML and JSON files here to diagnose build-time issues before deploying.
