Merge pull request #724 from Vincamine/w--video-hosting

[Docs] Add Guidelines for External Media and Video Hosting

Author: zihanKuang

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

@@ -170,7 +170,16 @@ Enhance your course with images and other visual aids. The recommended and stand
 For all assets, please use the Page Bundling method. It simplifies asset management by co-locating images with the Markdown files that use them.
 {{< /alert >}}
 
-**How to Add an Image**
+### Size Limits for Embedded Media
+While there's no hard-coded size limit, we enforce these practical constraints:
+| Media Type | Recommended Max Size | Impact Beyond Limit          |
+|------------|----------------------|------------------------------|
+| Video      | 50 MB                | Slow builds, CI failures     |
+| Image      | 5 MB                 | Hugo memory overflow         |
+| PDF        | 20 MB                | Browser loading delays       |
+
+
+### How to Add an Image
 
 1.  Place your image file (e.g., `hugo-logo.png`) in the **same directory** as your Markdown file (e.g., `01-pods.md`). 
 
@@ -184,18 +193,44 @@ For all assets, please use the Page Bundling method. It simplifies asset managem
 The `usestatic` shortcode is **deprecated** and should not be used!
 {{< /alert >}}
 
-**How to Add a Video**
+### How to Add a Video
+
+**Page Bundling (Recommended)**
+```markdown
+<video controls width="100%">
+  <source src="video-demo.mp4" type="video/mp4">
+</video>
+```
 
-```text
-{{</* card 
-title="Video: Example" */>}}
-<video width="100%" height="100%" controls>
-    <source src="https://exmaple.mp4" type="video/mp4">
-    Your browser does not support the video tag.
+**External Hosting (Large Files)**
+```markdown
+{{</* card title="Video Tutorial" */>}}
+<video controls preload="metadata">
+  <source src="https://cdn.yourcompany.com/video.mp4" type="video/mp4">
+  Your browser doesn't support HTML5 video.
 </video>
 {{</* /card */>}}
 ```
 
+#### External Hosting Recommendations
+For optimal performance, we recommend hosting large videos on dedicated platforms:
+- **YouTube** (Free, public/private options)
+- **AWS S3** (Requires bucket & CORS configuration)
+- **Cloudflare Stream** (Paid, enterprise-grade)
+- **Vimeo** (Paid, professional features)
+
+
+#### Critical Considerations
+- Best practice: Page Bundling
+
+- Accessibility: Always include subtitle tracks (VTT format)
+
+- Thumbnails: Set custom posters with ```poster="image.jpg"```
+
+- Bandwidth: Self-hosted videos may incur significant costs
+
+- Authentication: For private videos, use signed URLs (S3) or unlisted (YouTube)
+
 ## 4. Build and Preview Locally
 
 Before publishing, it is crucial to preview your content locally to check for formatting errors, broken links, and overall structure.
@@ -343,4 +378,19 @@ make clean
 
     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.
 
+6. **Why does my local build fail when adding large videos?**
+
+    Hugo's default memory limit is 512MB. For videos >50MB:
+    ```bash
+    hugo server --memlimit 2GB
+    ```
+
+7.  **How to securely host private training videos?**
+
+    Use AWS S3 with signed URLs:
+    ```html
+    <video src="{{</* s3_signed_url path="training/private.mp4" */>}}">
+    ```
+
+
 [^1]: The auto-generated learning path ID feature will be launched soon.