|
| 1 | +# Layer5 Academy |
1 | 2 |
|
2 | | -# Layer5 Academy - Content Starter Template |
| 3 | +**Layer5 Academy** is the **official content repository** for Layer5's learning platform, hosting all official learning paths, challenges, and certifications. |
| 4 | +It is built with [Hugo](https://gohugo.io/) and integrated into a multi-repository architecture for rapid local preview and automated cloud deployment. |
3 | 5 |
|
4 | | -This repository is a starter template for creating custom learning paths and courses on the [Layer5 Academy](https://cloud.layer5.io/academy/overview). It provides the necessary file structure and a working example to help you get started quickly. |
| 6 | +--- |
5 | 7 |
|
6 | | -This guide will walk you through setting up your own content repository, creating courses, and previewing them locally. |
| 8 | +## 📚 Overview |
7 | 9 |
|
8 | | -> For more in-depth documentation, see the official [Layer5 Academy docs](https://docs.layer5.io/cloud/academy/). |
| 10 | +- **Role**: Primary source of official Academy content |
| 11 | +- **Features**: |
| 12 | + - Fully structured, production-ready reference |
| 13 | + - Rapid local preview loop for Markdown content changes |
| 14 | + - Integrated into the platform's build and deployment pipeline |
9 | 15 |
|
10 | | -## Prerequisites |
| 16 | +--- |
11 | 17 |
|
12 | | -Before you begin, ensure you have the following installed on your system: |
| 18 | +## Table of Contents |
13 | 19 |
|
14 | | - * [**Hugo**](https://gohugo.io/getting-started/installing/) (extended version) （version 0.147.9） |
15 | | - * [**Go**](https://go.dev/doc/install) （version 1.12） |
| 20 | +- [Related Repositories](#-related-repositories) |
| 21 | +- [Quick Start (Local Preview)](#-quick-start-local-preview) |
| 22 | +- [Repository Structure](#repository-structure) |
| 23 | +- [Contributing](#contributing) |
| 24 | +- [Publishing](#publishing) |
| 25 | +- [Resources](#resources) |
16 | 26 |
|
17 | | -## Getting Started |
| 27 | +--- |
18 | 28 |
|
19 | | -Follow these steps to create your own learning path using this template. |
| 29 | +## Related Repositories |
20 | 30 |
|
21 | | -### 1. Fork & Clone the Repository |
| 31 | +The Academy platform is composed of multiple repositories, each with a specific role: |
22 | 32 |
|
23 | | -First, create a copy of this repository under your own GitHub account. |
| 33 | +- **[`academy-theme`](https://github.com/layer5io/academy-theme)** – Controls the site’s layout, styles, typography, and shortcodes. Included automatically via Go modules. |
| 34 | +- **[`academy-example`](https://github.com/layer5io/academy-example)** – Starter template for organizations to create their own content repositories following Academy standards. |
| 35 | +- **[`academy-build`](https://github.com/layer5io/academy-build)** – Central build and deployment pipeline. Aggregates content from multiple repos with the theme to generate and publish the complete Academy site. |
24 | 36 |
|
25 | | - - **Fork** this [academy-example](https://github.com/layer5io/academy-example) repository. |
26 | | - - Clone your forked repository: |
27 | | - ```bash |
28 | | - # Replace <your-username> with your GitHub username |
29 | | - git clone https://github.com/<your-username>/academy-example.git |
30 | | - cd academy-example |
31 | | - ``` |
| 37 | +- For more detailed information: [Academy / Platform Development](https://docs.layer5.io/cloud/academy/platform-development/) |
| 38 | +--- |
32 | 39 |
|
33 | | -### 2. Update the Go Module Path |
| 40 | +## Quick Start (Local Preview) |
34 | 41 |
|
35 | | - - Open the `go.mod` file at the root of the project. |
36 | | - - Change the first line from: |
37 | | - ```go |
38 | | - module github.com/layer5io/academy-example |
39 | | - ``` |
40 | | - - To match your repository's path: |
41 | | - ```go |
42 | | - module github.com/<your-username>/academy-example |
43 | | - ``` |
44 | | - - Save the file, then commit and push the change. |
| 42 | +> Use this workflow for a fast preview loop when editing Markdown content. |
45 | 43 |
|
46 | | -### 3. Configure Your Organization Directories |
47 | | -
|
48 | | -The Academy platform uses an **Organization ID** to keep content separate and secure. You must get this ID from the Layer5 CLoud before proceeding. |
49 | | -
|
50 | | -Once you have your UID, rename the placeholder directories: |
51 | | -
|
52 | | - - Rename `content/learning-paths/your-org-uid` to `content/learning-paths/<your-organization-uid>` |
53 | | - - Rename `static/your-org-uuid` to `static/<your-organization-uid>` |
54 | | - - Rename `layouts/shortcodes/your-org-uuid` to `layouts/shortcodes/<your-organization-uid>` |
55 | | -
|
56 | | -### 4. Add Your Content |
57 | | -
|
58 | | -Now you're ready to create your learning path. The structure is: **Learning Path → Course → Chapter → Lesson**. |
59 | | - |
60 | | -A high-level view of the structure looks like this: |
61 | | - ```text |
62 | | - content/ |
63 | | - └── learning-paths/ |
64 | | - ├── _index.md |
65 | | - └── <your-organization-uid>/ |
66 | | - └── <your-learning-path>/ |
67 | | - ├── _index.md |
68 | | - └── <your-course-1>/ |
69 | | - └── <your-course-2>/ |
70 | | - ├── _index.md |
71 | | - └── content/ |
72 | | - └── your-lesson-1.md |
73 | | - └── your-lesson-2.md |
74 | | - ``` |
75 | | - |
76 | | - - **Delete the example content** inside `content/learning-paths/<your-organization-uid>/`. |
77 | | - - **Create your folder structure** following the example's hierarchy. |
78 | | - - **Add your lessons** as Markdown (`.md`) files inside the `content` directory of a course. |
79 | | - - **Use frontmatter** at the top of your `_index.md` and lesson files to define titles, descriptions, and weights. |
80 | | -
|
81 | | -### 5. Add Assets (Images & Videos) |
82 | | -
|
83 | | -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. |
84 | | -
|
85 | | -**How to Add an Image** |
| 44 | +```bash |
| 45 | +# Clean up and verify Go module dependencies |
| 46 | +go mod tidy |
86 | 47 |
|
87 | | -1. Place your image file (e.g., `hugo-logo.png`) in your scoped static directory: |
| 48 | +# Install necessary tools and modules |
| 49 | +make setup |
88 | 50 |
|
89 | | - ```text |
90 | | - static/<your-organization-uid>/images/hugo-logo.png |
91 | | - ``` |
92 | | -2. In your `lesson-1.md` file, embed the image using the `usestatic` shortcode. The `path` is relative to your scoped static folder: |
| 51 | +# Start the local Hugo development server |
| 52 | +make site |
93 | 53 |
|
94 | | - ```text |
95 | | - ![The Hugo Logo]({{</* usestatic path="images/hugo-logo.png" */>}}) |
96 | | - ``` |
| 54 | +``` |
97 | 55 |
|
98 | | -Then the system will automatically convert this into the correct URL when building the site. |
| 56 | +Open your browser at: ```http://localhost:1313/academy```. Note: The local preview uses the ```academy-theme```. In production, content is wrapped by the Layer5 Cloud UI, so minor visual differences may occur. For end-to-end validation, test with the ```academy-build``` repository. |
99 | 57 |
|
100 | | -**How to Add a Video** |
| 58 | +--- |
101 | 59 |
|
102 | | -```text |
103 | | -{{</* card |
104 | | -title="Video: Example" */>}} |
105 | | -<video width="100%" height="100%" controls> |
106 | | - <source src="https://exmaple.mp4" type="video/mp4"> |
107 | | - Your browser does not support the video tag. |
108 | | -</video> |
109 | | -{{</* /card */>}} |
| 60 | +## Repository Structure |
| 61 | +```bash |
| 62 | +layer5-academy/ |
| 63 | +├── content/ # All learning paths, challenges, and certifications (Markdown) |
| 64 | +├── layouts/ # Shortcodes or layout overrides (if any) |
| 65 | +├── static/ # Static assets (images, videos, etc.) |
| 66 | +├── hugo.yaml # Hugo site configuration |
| 67 | +├── go.mod # Go module dependencies (includes academy-theme) |
| 68 | +└── Makefile # Commands for local dev & build |
110 | 69 | ``` |
| 70 | +--- |
111 | 71 |
|
112 | | -### 6. Local Development |
| 72 | +## Contributing |
113 | 73 |
|
114 | | -To preview your content locally, run the Hugo server from the project root: |
| 74 | +We welcome contributions to improve: |
| 75 | +- Content accuracy and clarity |
| 76 | +- Additional learning paths, challenges, or certifications |
| 77 | +- Shortcodes, layouts, and formatting |
115 | 78 |
|
| 79 | +Workflow: |
| 80 | +1. Fork this repository. |
| 81 | +2. Create a feature branch: |
116 | 82 | ```bash |
117 | | -hugo server |
| 83 | +git checkout -b feature/your-feature |
118 | 84 | ``` |
| 85 | +3. Commit changes: |
| 86 | +```bash |
| 87 | +git commit -m "Describe your change" |
| 88 | +``` |
| 89 | +4. Push and open a Pull Request. |
119 | 90 |
|
120 | | -This will start a local server. You can view your content and check for formatting issues before publishing. |
121 | | -
|
122 | | -> The local preview uses basic styling. Full Academy branding and styles will be applied after your content is integrated into the cloud platform. |
| 91 | +See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. |
123 | 92 |
|
124 | | -### 7. Going Live |
| 93 | +--- |
125 | 94 |
|
126 | | -Once your content is complete and tested locally: |
| 95 | +## Publishing |
| 96 | +- **Official content**: Merged changes are automatically integrated into the central academy-build pipeline and deployed to the Academy platform. |
| 97 | +- **Organization-owned content**: Use academy-example as a starting point. |
| 98 | +After creating a release, the academy-build pipeline will fetch and publish your content to Layer5 Cloud (requires organization ID and token). |
127 | 99 |
|
128 | | -1. Push all your changes to your forked repository on GitHub. |
129 | | -2. **[Connect](https://layer5.io/company/contact) the Layer5 Team** via Slack, email, or by opening a GitHub issue. |
130 | | -3. Provide the URL to your content repository. |
| 100 | +--- |
131 | 101 |
|
132 | | -A Layer5 administrator will then integrate your repository into the main Academy platform. After integration, your learning paths will be visible on the official [Layer5 Cloud site](https://cloud.layer5.io/academy/overview). |
| 102 | +## Resources |
| 103 | +- Academy Documentation: https://docs.layer5.io/cloud/academy |
| 104 | +- Content Creation Guide: https://docs.layer5.io/cloud/academy/creating-content |
| 105 | +- Community Slack: https://slack.layer5.io |
0 commit comments