add advanced-contribution-guide

Signed-off-by: ZihanKuang <zihan_kuang@outlook.com>

Author: zihanKuang

content/en/cloud/academy/advanced-contribution-guide/index.md

@@ -1,36 +1,36 @@
 ---
 title: "Advanced Contributor Guide"
-weight: 4
+weight: 5
 description: >
-  An advanced guide to the Layer5 Academy architecture, multi-repository workflow, and development best practices for platform contributors.
+  An advanced guide to the Layer5 Academy architecture, multi-repository workflow, and development best practices for contributors.
 categories: [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.
+This guide walks you through the Layer5 Academy platform's multi-repository architecture. You will learn the role of each core component and master the practical workflows for theme development, local testing, and end-to-end validation with Layer5 Cloud.
 
 ## The Multi-Repository Model
 
-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.
+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, style, 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.
 
 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.
 
-> [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. 
+## Core Repositories
 
-## A Deep Dive into the Core Repositories
-
-The Layer5 Academy platform is composed of several core repositories, each with a distinct purpose.
+The Layer5 Academy platform is composed of several core repositories.
 
 ### [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.
 
+Content repositories automatically import this theme as a Go Module. As a content creator, you do not need to fork or clone this repository; your academy will use these styles by default.
+
 ### [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.
 
-> [Learn How](../cloud/academy/creating-your-learning-path/index.md) to create your own learning path
+> [Learn How](../creating-your-learning-path/) to create your own learning path
 
-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:
+This content repository doesn't build the final website itself. Instead, it uses an automated workflow to act as a "gatekeeper" for new content. When you create a new GitHub Release, it triggers the following process:
 
 1. **Sanity Check**: It first runs a local build to ensure the new content has no fundamental errors that would break the site.
 
@@ -44,62 +44,64 @@ This request effectively says: "A new version of content is ready for this organ
 
 **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`.
 
-This repository is the **"assembly factory"** and the central hub of the entire system. It holds the master plan for building the final website.
-
-When triggered, its automated process acts like a master assembly line:
+When its workflow is triggered, an automated process acts like a master assembly line:
 
 1.  **Collects Parts**: It begins by gathering all the necessary components—`academy-theme` and all the course content from the various content repositories.
 
 2.  **Assembles the Website**: Next, it combines everything. It applies the theme's design to all the course content, building a single, complete website.
 
 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.
 
-{{< 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 >}}
-
 ## Developer Workflows
 
-### When to Use Local Development and Previewing
-
-Use these workflows for rapid development and iteration on your local machine.
+### How to Develop and Preview Locally
 
-#### How to Preview Content Changes
+Use this workflow for rapid local development and iteration. If you're only changing Markdown files and want a fast preview loop, run these commands within a content repository (such as `layer5-academy`):
 
-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`):
+{{< alert type="info" title="layer5-academy as an Example" >}}
+We'll use [layer5-academy](https://github.com/layer5io/layer5-academy) for these examples because it hosts all official Layer5 learning paths. It serves as a feature-complete reference, allowing you to see how a complex, real-world content repository is structured.
+{{< /alert >}}
 
 1. `go mod tidy`: Cleans up and verifies Go module dependencies.
-2. `make setup`: Installs necessary tools and modules defined in the `Makefile`.
+2. `make setup`: Installs necessary tools and modules.
 3. `make site`: Starts the local Hugo development server.
 
 You can then view your content by navigating to `http://localhost:1313/academy`.
 
-#### How to Develop the Academy Theme
+### How to Develop the Academy Theme
 
-When you need to modify the `academy-theme` and see its effect on real content, you'll use the `go mod replace` directive:
+If you need to modify the `academy-theme` and see its effect on real content, you'll use the `go mod replace` directive:
 
 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:
+2. **Redirect the Dependency**: In the `go.mod` file of the content repository you're using for previewing (e.g., `layer5-academy`), 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. **Apply Changes and Relaunch**: Run `go mod tidy` to apply the `replace` directive you just added. Then, restart the server with `make site`. The local server will now use your local theme code, allowing you to see your changes instantly.
 
-### When to Use End-to-End Testing with Layer5 Cloud
+### How to Use End-to-End Testing with Layer5 Cloud
 
-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.
+Use this workflow for end-to-end testing that mirrors the production environment. This is the ultimate way to verify your changes work correctly within the Layer5 Cloud UI before they go live:
 
-Use this workflow to ensure your changes work correctly within the final Layer5 Cloud environment:
+All steps in this section should be performed from the root of your local `academy-build` repository.
 
-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:
+1. **Prepare Local Dependencies**: If you're testing local changes from other repositories (like a theme or content module), edit the `go.mod` file in `academy-build` to point to your local versions using a replace directive:
+   ```go
+   replace github.com/layer5io/academy-theme => ../academy-theme
+   replace github.com/layer5io/layer5-academy => ../layer5-academy
+   ```
+
+2. **Build Locally**: 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:
+
+3. **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.
+
+4. **Preview on Staging**: Your changes will be available on the [staging environment](https://staging-cloud.layer5.io/) within approximately 10 minutes.
 
 {{< 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.
@@ -116,3 +118,9 @@ make academy-prod
 ```
 
 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.
+
+### Best Practices
+
+1. **Keep Dependencies Clean**: After testing with local replace directives in your `go.mod` file, always remember to remove them and run `go mod tidy` before committing your changes. This prevents accidental check-ins of local paths.
+2. **Test Incrementally**: Start with local development for rapid iteration, then progress to holistic builds, and finally test in the staging environment.
+3. **Version Control**: Always commit your changes to version control before testing in staging to ensure you can track and revert changes if needed.