You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -14,7 +14,7 @@ This guide provides a step-by-step walkthrough for creating and organizing a new
14
14
Before you dive into creating your first learning path, it's helpful to be familiar with the core technologies and concepts used by the Academy platform.
15
15
16
16
-**Git and GitHub**: All learning content is managed in a Git repository.
17
-
-**Markdown**: All course and chapter content is written in standard Markdown.
17
+
-**Markdown**: All content is written in standard Markdown.
18
18
-**Hugo**: The entire Academy platform is built on the [Hugo](https://gohugo.io/) static site generator.
19
19
-**Academy Template & Theme**: We provide an `academy-example` repository that serves as a pre-configured template. [Layer5 Academy theme](https://github.com/layer5io/academy-theme) to ensure your content is styled correctly right out of the box.
20
20
-**A Layer5 Cloud Account**: Required to obtain your Organization ID and Personal Access Token for publishing.
@@ -65,7 +65,7 @@ The Academy uses a specific directory layout to keep each organization's content
65
65
Each learning path is tied to a specific organization and secured by a unique identifier (UUID). This is a system-generated ID that ensures your content is scoped only to your organization.
66
66
67
67
{{< alert type="info" title="How to Find Your Organization UUID?" >}}
68
-
You can find and copy your Organization UUID from your organization page on [Layer5 Cloud](https://cloud.layer5.io/identity/organizations).
68
+
You can find and copy your Organization UUID from your organization page on [Academy](https://cloud.layer5.io/academy).
69
69
{{< /alert >}}
70
70
71
71
2. **Create the Core Directories**
@@ -79,80 +79,92 @@ You can find and copy your Organization UUID from your organization page on [Lay
79
79
80
80
3. **Build the Content Hierarchy**
81
81
82
-
With the main folders in place, you can now structure your first course inside the `content` directory. The content is organized in a clear hierarchy: **Learning Path → Course → Chapter**.
82
+
With the main folders in place, you can now structure your first course inside the `content` directory. The content is organized in a clear hierarchy: A **Learning Path** contains **Courses**. A **Course** is primarily broken down into **Modules**, but can also conclude with a final **Quiz** that serves as a course exam. Finally, a **Module** consists of individual **Pages**, **Quizzes**, and **Labs**.
83
83
84
84
A high-level view of the structure looks like this:
Each folder represents a level in the hierarchy, and the `_index.md` file within a folder defines the metadata (like titleand description) for that level. The final `.md` files are your individual Chapter.
105
+
Each folder represents a level in the hierarchy. The `_index.md` file within a folder is crucial as it defines the metadata for that level, such as its `title`, `description`, and `type` (e.g., `type: "course"`). The final `.md` files represent your individual learning activities: **Pages** and **Labs** are typically found inside Modules, while **Quizzes** can be found inside Modules (for knowledge checks) or directly under a Course (as a final exam).
102
106
103
107
> For a deeper understanding of how Hugo uses `_index.md` to create content sections, you can refer to the official [Hugo Page Bundles documentation](https://gohugo.io/content-management/page-bundles/).
104
108
105
109
4. **Front matter**
106
110
107
-
Use this at the top of each **Learning Path** page (`learning-paths/<orgId>/<slug>/_index.md` or similar):
111
+
Front matter is the configuration block at the top of every content file that defines its metadata. The most critical field is type, which tells the Academy how to render the content.
112
+
113
+
The front matter configuration varies slightly depending on whether you are creating a Learning Path/Challengs, Course, Module, or Page. The following examples for a Learning Path and a Course illustrate a typical setup.
114
+
115
+
**Learing Path Frontmatter**
108
116
109
117
```yaml
110
118
---
111
-
title: "Advanced Course"
112
-
description: "This ADVANCED - Course is where to get the technical knowledge."
119
+
type: "learning-paths"
120
+
title: "Cloud Fundamentals"
121
+
description: "A learning path focused on providing the technical knowledge required for advanced topics."
113
122
weight: 5
114
-
banner: "images/exoscale-icon.svg"
115
-
id: "754627a3-7993-4b01-a7f0-c66c0212a1a1"
116
-
tags: [orchestration]
117
-
categories: [introductory]
123
+
banner: "images/kubernetes-icon.svg"
124
+
id: "754627a3-2323-4545-a7f0-c66c0212a1a1"
125
+
tags: [kubernetes, infrastructure]
126
+
categories: "cloud"
118
127
---
119
128
```
120
129
121
-
> Place this frontmatter in the Markdown file that represents the learning path index page.
| All | `description` | ✅ | A brief summary of the content. |
153
+
| All | `weight` | ✅ | Controls the display order (lower numbers appear first). |
154
+
| All | `draft` | ❌ | If `true`, the page will not be published. |
155
+
| All | `type` |✅| Defines the content's role. Optional values: `challenge`, `learning-path`, `course`, `module`, `page`, `quiz`, or `lab`. |
156
+
| **Course** | `level`| ❌ | Thedifficulty level of the content. Optional values: `beginner`, `intermediate`, `advanced`. |
157
+
| **Learning Path** | `id` | ✅ | **Crucial.** A stable UUIDfor tracking progress. **Do not change.** [^1] |
158
+
| **Learning Path**, **Course**, **module** | `tags`| ❌ | Keywordsfor content discovery. Multiple tags can be selected. |
159
+
| **Learning Path**, **Course**, **module** | `categories`|❌ | The main categories for the content. Only one can be selected. |
160
+
| **Learning Path**, **Course** | `banner`| ❌ | Path to an image in the `static` folder, e.g., `images/icon.svg`. |
153
161
154
162
> For a complete list of all predefined variables and advanced usage, please refer to the official [Hugo FrontMatter documentation](https://gohugo.io/content-management/front-matter/).
155
163
164
+
{{< alert type="info" title="Be Careful About Name Changes" >}}
165
+
Renaming a course or module after publication would break the learning path tracking for enrolled learners. It's like changing pages while someone is following the story. Consider updating the module’s description, adding an introductory note, or creating a versioned copy.
166
+
{{< /alert >}}
167
+
156
168
## 3. Add Assets and Interactive Content
157
169
158
170
Enhance your course with images and other visual aids. The recommended and standard method for adding images is Page Bundling. This approach involves placing your image files directly alongside the Markdown content they belong to, which is simpler and keeps content organized.
@@ -161,11 +173,20 @@ Enhance your course with images and other visual aids. The recommended and stand
161
173
For all assets, please use the Page Bundling method. It simplifies asset management by co-locating images with the Markdown files that use them.
162
174
{{< /alert >}}
163
175
164
-
**How to Add an Image**
176
+
### Size Limits for Embedded Media
177
+
While there's no hard-coded size limit, we enforce these practical constraints:
For optimal performance, we recommend hosting large videos on dedicated platforms:
220
+
- **YouTube** (Free, public/private options)
221
+
- **AWS S3** (Requires bucket & CORS configuration)
222
+
- **Cloudflare Stream** (Paid, enterprise-grade)
223
+
- **Vimeo** (Paid, professional features)
224
+
225
+
226
+
#### CriticalConsiderations
227
+
- Best practice: PageBundling
228
+
229
+
- Accessibility: Always include subtitle tracks (VTT format)
230
+
231
+
- Thumbnails: Set custom posters with ```poster="image.jpg"```
232
+
233
+
- Bandwidth: Self-hosted videos may incur significant costs
234
+
235
+
- Authentication: For private videos, use signed URLs (S3) or unlisted (YouTube)
236
+
190
237
## 4. Build and PreviewLocally
191
238
192
239
Before publishing, it is crucial to preview your content locally to check for formatting errors, broken links, and overall structure.
@@ -334,4 +381,19 @@ make clean
334
381
335
382
The structure is defined by your folder hierarchy. A learning path is a directory, and each course is a sub-directory within that path. This folder structure in your `content` directory directly maps to the learning path structure presented to users.
336
383
384
+
6. **Why does my local build fail when adding large videos?**
385
+
386
+
Hugo's default memory limit is 512MB. For videos >50MB:
387
+
```bash
388
+
hugo server --memlimit 2GB
389
+
```
390
+
391
+
7. **How to securely host private training videos?**
Copy file name to clipboardExpand all lines: content/en/cloud/academy/extending-the-academy/index.md
+6-5Lines changed: 6 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,12 +39,13 @@ You don't need to be a web developer to create beautiful and effective learning
39
39
40
40
Your content is structured hierarchically to create a clear and logical learning experience for your users.
41
41
42
-
At the highest level, you have a **Learning Path**, which serves as a container for a specific specialization or topic. Each Learning Path is made up of one or more **Courses**, and each Course is further broken down into individual **Chapters**. This modular structure makes your content easy to navigate, manage, and update.
42
+
At the highest level, you have a **Learning Path**, which contains one or more **Courses**. Each Course is broken down into **Modules**, and each Module consists of individual learning activities like **Pages** (for text), **Quizzes** (for knowledge checks), and **Labs** (for hands-on practice). This modular structure makes your content easy to navigate, manage, and update.
43
43
44
-
For example, a Learning Path titled "Mastering Kubernetes" might contain:
45
-
- A Course named "Core Concepts", which includes Chapters on "Pods", "Services", and "Deployments".
46
-
- Another Course named "Advanced Networking", with Chapters on "Ingress" and "Service Mesh".
44
+
For example, a **Learning Path** named **"Mastering Kubernetes"** might contain:
45
+
* A **Course** on **"Core Concepts"**, which is broken down into multiple modules:
46
+
* **Module 1: "Workload Fundamentals"**, containing a **Page** on the "Anatomy of a Pod" and a hands-on **Lab** for "Scaling Deployments".
47
+
* **Module 2: "Networking Principles"**, containing a **Page** that covers "Services and Ingress" and a **Quiz** on networking concepts.
To ensure security and isolation, all of your content files must be placed within a directory named for your organization UUID. You'll learn the specifics of how to do this in our [hands-on tutorial](/cloud/academy/creating-your-learning-path/).
0 commit comments