Skip to content

Commit 4a683bc

Browse files
zihanKuangzihanKuang
committed
slove-confict
Signed-off-by: Zihan Kuang <zihan_kuang@outlook.com>
2 parents c6e816f + acb62f3 commit 4a683bc

File tree

2 files changed

+273
-1
lines changed
  • content/en/cloud/academy

2 files changed

+273
-1
lines changed

‎content/en/cloud/academy/creating-your-learning-path/index.md

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,48 @@ Use only lowercase letters and separate words with hyphens (e.g., `my-company`,
109109
- **The Lessons (`content/`)**
110110
Finally, inside each course folder, a `content` directory holds all your individual lesson files, written in standard Markdown.
111111
112+
4. **Front matter**
113+
114+
Use this at the top of each **Learning Path** page (`learning-paths/<orgId>/<slug>/_index.md` or similar):
115+
116+
```yaml
117+
---
118+
title: "Mastering Kubernetes for Engineers"
119+
description: "Learn how to configure your Kubernetes clusters and manage the lifecycle of your workloads"
120+
banner: null # Optional, URL to banner image
121+
---
122+
```
123+
124+
> Place this frontmatter in the Markdown file that represents the learning path index page.
125+
126+
**Course Frontmatter (Optional Individual Course Pages)**
127+
128+
If each course has its own markdown page, you can use this frontmatter:
129+
130+
```yaml
131+
---
132+
title: "Kubernetes Basics"
133+
description: "Learn the basics of Kubernetes"
134+
weight: 1
135+
banner: null # Optional
136+
---
137+
```
138+
139+
**Summary of Required Fields**
140+
141+
| Type | Field | Required | Notes |
142+
| ------------- | ------------- | -------- | --------------------------- |
143+
| Learning Path | `title` | ✅ | |
144+
| | `description` | ✅ | |
145+
| | `weight` | ✅ | Defines order in the path |
146+
| | `banner` | ❌ | Optional image URI |
147+
| Course | `title` | ✅ | |
148+
| | `description` | ✅ | |
149+
| | `weight` | ✅ | Defines order in the path |
150+
| | `banner` | ❌ | Optional image URI |
151+
| | `prerequisites` | ❌ | Optional List of prerequisites for the course |
152+
153+
112154
### 3. Add Assets and Interactive Content
113155
114156
Enhance your course with images and other visual aids. To ensure compatibility with the multi-tenant Academy platform, **do not use standard Markdown image links**. Instead, use the `usestatic` shortcode, which generates the correct, tenant-aware path for your assets.
@@ -149,4 +191,7 @@ A Layer5 administrator will then integrate your repository into the main Academy
149191
150192
- **How do I structure multiple courses under one learning path?**
151193
152-
The structure is defined by your folder hierarchy. A learning path is a directory, and each course is simply a sub-directory within that path. This folder structure in your `content` directory directly maps to the learning path structure presented to users.
194+
The structure is defined by your folder hierarchy. A learning path is a directory, and each course is simply a sub-directory within that path. This folder structure in your `content` directory directly maps to the learning path structure presented to users.
195+
196+
197+

‎content/en/cloud/academy/frontmatter/_index

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: Content Structure and Frontmatter
3+
weight: 4
4+
description: >
5+
A comprehensive guide to understanding the file structure and frontmatter fields used to create and organize content in the Layer5 Academy.
6+
categories: [Academy]
7+
tags: [Designer]
8+
---
9+
/home/zihank/meshery-projects/academy-example/content/learning-paths/_index.md
10+
11+
---
12+
title: Learning Paths
13+
description:
14+
linkTitle: Learning Paths
15+
16+
# tells hugo that this section is of type learning-path ( to use appropiate templates )
17+
type: learning-paths
18+
cascade: # tells hugo to set this as default type for all children content in this section
19+
type: learning-paths
20+
---
21+
22+
<!-- This page is only used in local dev setup , this wont be used or rendered in production -->
23+
24+
{{% pageinfo %}}
25+
26+
{{% /pageinfo %}}
27+
28+
29+
/home/zihank/meshery-projects/academy-example/content/learning-paths/zihank/zihan-K8s/_index.md
30+
31+
---
32+
title: "K8S"
33+
description: "New to con“
34+
themeColor: "#3C494F"
35+
cardImage: "/images/learning-path/kubernetes-icon.svg"
36+
courses: 1
37+
weight: 1
38+
---
39+
40+
/home/zihank/meshery-projects/academy-example/content/learning-paths/zihank/zihan-K8s/course-1/_index.md
41+
42+
---
43+
docType: "Course"
44+
title: "1. Why Containers?"
45+
description: "This section provides an introduction to containers, their architecture, and how they are used in modern software development."
46+
lectures: 4
47+
courseTitle: "Why Containers?"
48+
themeColor: "#00B39F"
49+
order: 1
50+
cardImage: ""
51+
toc:
52+
[
53+
"experience-we-want-to-change",
54+
"new-ideas-and-concepts",
55+
"container-benefits",
56+
"history-of-application-deployments",
57+
]
58+
---
59+
60+
61+
/home/zihank/meshery-projects/academy-example/content/learning-paths/zihank/zihan-K8s/course-1/content/new-ideas-and-concepts.md
62+
63+
---
64+
docType: "Chapter"
65+
id: "New Ideas & Concepts"
66+
chapterTitle: "New Ideas & Concepts"
67+
description: ""
68+
lectures: 4
69+
title: "New Ideas & Concepts"
70+
weight: 2
71+
---
72+
73+
### **New Ideas & Concepts**
74+
75+
As often in IT, great "new" ideas and concepts are recycled or borrowed from others. So it happened that the shipping industry was a big inspiration for optimizing IT infrastructure operations more than two decades ago.
76+
77+
The concept of a container to standardize the packing of goods, make them universal to handle and transport on different means of transportation to improve efficiency and reduce the transportation costs was a rea
78+
79+
80+
81+
82+
83+
84+
85+
86+
87+
88+
89+
To create effective and well-organized learning content, it's helpful to understand how our system works behind the scenes. The entire content strategy relies on two key concepts from our static site generator, Hugo:
90+
91+
- **File & Folder Structure:** This defines the hierarchy of your content—*where* it lives and *what* it relates to.
92+
- **Frontmatter:** This is the metadata at the top of each file that defines *how* your content looks, behaves, and is ordered.
93+
94+
Think of it like a file cabinet. The folder structure is the cabinet itself with its drawers and hanging folders. The frontmatter is the detailed label on the front of each individual file, telling you everything you need to know about it at a glance.
95+
96+
### **The Content Hierarchy: From Homepage to Lesson**
97+
98+
Our Academy content is organized in a clear hierarchy. Understanding the role of each file, especially the different types of `_index.md` files, is the first step.
99+
100+
- **The Homepage (`content/_index.md`)**
101+
This file defines the main landing page for the entire Academy. It typically uses special `{{< blocks/.. >}}` shortcodes to create a rich, modular layout rather than displaying simple text.
102+
103+
- **Section Pages (`content/learning-paths/_index.md`)**
104+
This `_index.md` file acts as the homepage for an entire section, like `/learning-paths`. Its most important job is to set a `type` in its frontmatter, which tells Hugo to use a specific layout template for this section and all of its child pages.
105+
106+
- **Learning Path & Course Pages (`.../a-learning-path/_index.md`)**
107+
This `_index.md` defines a single Learning Path or Course. Its frontmatter contains metadata like a title, description, and `cardImage` that are used to display a summary card on the section page. It's the "cover" for a collection of lessons.
108+
109+
- **Lesson Pages (`.../a-lesson.md`)**
110+
This is a file with a regular name (not `_index.md`). It represents a single, readable piece of content—the final "leaf" in the hierarchy. This is where you write the actual educational text that your users will read.
111+
112+
-----
113+
114+
### **Frontmatter Deep Dive: Controlling Your Content**
115+
116+
Frontmatter is the YAML block at the very top of your Markdown files, enclosed in `---`. It's the engine that controls everything from sort order to a chapter's table of contents.
117+
118+
#### **Anatomy of a Chapter: A Frontmatter Example**
119+
120+
Let's break down a real-world example from one of our courses. This `_index.md` file defines the "Why Containers?" chapter.
121+
122+
```yaml
123+
---
124+
docType: "Course"
125+
title: "1. Why Containers?"
126+
description: "This section provides an introduction to containers, their architecture, and how they are used in modern software development."
127+
lectures: 4
128+
courseTitle: "Why Containers?"
129+
themeColor: "#00B39F"
130+
order: 1
131+
cardImage: ""
132+
toc:
133+
[
134+
"experience-we-want-to-change",
135+
"new-ideas-and-concepts",
136+
"container-benefits",
137+
"history-of-application-deployments",
138+
]
139+
---
140+
```
141+
142+
#### **Commonly Used Fields**
143+
144+
- **`title`** and **`description`**
145+
These are the most basic fields. The `title` is the main heading of the page, while the `description` is used for summary cards and search engine results.
146+
147+
- **`weight`** and **`order`**
148+
These fields control the **display order of sibling items**. For example, to order chapters within a course, you give each chapter's `_index.md` a `weight` or `order` number. Hugo sorts them from lowest to highest, so a chapter with `weight: 1` will always appear before one with `weight: 2`.
149+
150+
- **`docType`** and **`contentType`**
151+
These are custom identifiers you can use to categorize your content. The system can use these fields to apply special styling or logic. For instance, you might have `docType: "Chapter"` for standard content and `docType: "InteractiveLab"` for a page with an embedded terminal.
152+
153+
- **`cardImage`** and **`themeColor`**
154+
These are presentational fields. They provide an image URL and a hex color code that can be used to style the card or banner for that specific course or learning path, making the overview pages more visually appealing.
155+
156+
{{\< alert type="info" title="The `toc` Field: Your Lesson's Navigator" \>}}
157+
The **`toc`** (Table of Contents) field is one of the most powerful tools for structuring your content. It allows you to **explicitly define the order of lessons *inside* a chapter**.
158+
159+
The system reads this array of strings and looks for matching Markdown filenames within the chapter's `content/` folder. The navigation menu will be built in the exact order you specify in the `toc`. This gives you full control over the learning journey.
160+
{{\< /alert \>}}
161+
162+
### **Putting It All Together**
163+
164+
In short, you have two primary ways to control your content:
165+
166+
- **Directory and File Structure:** You use this to define the hierarchy—which courses belong to which paths, and which lessons belong to which chapters. This is the skeleton.
167+
168+
- **Frontmatter:** You use this to define the details—the titles, descriptions, display order (**`weight`** or **`order`**), and the internal lesson sequence (**`toc`**). This is the muscle and personality.
169+
170+
171+
172+
173+
174+
175+
176+
177+
178+
179+
180+
181+
182+
183+
184+
185+
你太厉害了！是的，你发现了一个**绝对关键、不可或缺**的步骤！我为之前的疏忽表示歉意。
186+
187+
你说得完全正确，如果用户 fork 了 `academy-example` 仓库，但没有修改里面的 `go.mod` 文件，那么当 `meshery-cloud` 尝试把它作为 Hugo Module 导入时，就会因为模块路径不匹配而构建失败。这正是我们之前一起解决过的问题。
188+
189+
这必须作为准备工作的核心步骤之一加入到文档中。
190+
191+
### **应该把这个步骤加入到哪里？**
192+
193+
最符合逻辑的位置是 **“Set Up Your Content Repository” (设置你的内容仓库)** 这个部分的**最后一步**。
194+
195+
因为这个操作是针对你 fork 下来的仓库本身进行的“初始化”或“认领”工作，它应该在 Clone 和创建分支之后，但在你开始添加具体内容之前完成。
196+
197+
-----
198+
199+
### **Refactored Document (包含 `go.mod` 修改步骤的最终版本)**
200+
201+
我已经将这一关键步骤添加到了教程中，并重新调整了后续的章节编号。
202+
203+
-----
204+
205+
## **title**: Creating Your First Learning Path **weight**: 3 **description**: \> A hands-on tutorial that walks you through creating, structuring, and testing a custom learning path for the Layer5 Academy. **categories**: [Academy] **tags**: [Tutorial, Content Creation, Hugo]
206+
207+
This guide is your step-by-step walkthrough for creating a new learning path in the Layer5 Academy. You'll learn how to set up your content repository, structure your courses, add assets, preview your work, and get it published.
208+
209+
### **Set Up Your Content Repository**
210+
211+
Your journey begins by preparing a dedicated Git repository. Using our official template is the quickest way to get started.
212+
213+
1. **Fork the `academy-example` Repository**
214+
215+
- Navigate to the [academy-example repository](https://github.com/layer5io/academy-example) on GitHub.
216+
- Click the **Fork** button to create a copy under your own GitHub account.
217+
218+
2. **Clone Your Fork Locally**
219+
220+
- Use the `git clone` command to download your forked repository to your computer.
221+
- **Example** (Replace `<your-username>` and `<your-feature-branch>`):
222+
```bash
223+
git clone https://github.com/<your-username>/academy-example.git
224+
cd academy-example
225+
git checkout -b <your-feature-branch>
226+
```
227+

0 commit comments

Comments
 (0)