Skip to content

Commit 3ba8965

Browse files
leecalcoteleecalcote
authored
Merge pull request #123 from RanitMukherjee/patch-1
Update README.md
2 parents 9bddafe + 738fee8 commit 3ba8965

File tree

1 file changed

+172
-4
lines changed

1 file changed

+172
-4
lines changed

‎README.md‎

Lines changed: 172 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,179 @@
11
# Exoscale Academy
22

3+
Welcome to **Exoscale Academy**, the dedicated cloud education and training platform powered by Layer5. This repository provides a comprehensive framework for creating, organizing, and publishing structured learning paths, courses, and lessons tailored for Exoscale users and cloud practitioners.
34

5+
## Table of Contents
46

5-
### Contributing
7+
- [Prerequisites](#prerequisites)
8+
- [Getting Started](#getting-started)
9+
- [Repository Structure](#repository-structure)
10+
- [Content Authoring Workflow](#content-authoring-workflow)
11+
- [Managing Assets (Images & Videos)](#managing-assets-images--videos)
12+
- [Local Development](#local-development)
13+
- [Deploying & Going Live](#deploying--going-live)
14+
- [Contributing](#contributing)
15+
- [Site Framework](#site-framework)
16+
- [License](#license)
617

7-
To learn to create and publish learning paths, courses, chapters, challenges, and so on see the documentation at https://docs.layer5.io/cloud/academy.
18+
## Prerequisites
819

20+
Before you begin, ensure you have:
921

10-
#### Site Framework
11-
Using Golang, built on Hugo, integrated with Layer5 Cloud. See the https://github.com/layer5io/academy-theme and https://github.com/layer5io/academy-template as relevant resources.
22+
- [**Hugo**](https://gohugo.io/getting-started/installing/) (extended version, recommended v0.147.9 or later)
23+
- [**Go**](https://go.dev/doc/install) (v1.12 or later)
24+
25+
## Getting Started
26+
27+
1. **Clone the Repository**
28+
29+
```bash
30+
git clone https://github.com/layer5io/exoscale-academy.git
31+
cd exoscale-academy
32+
```
33+
34+
2. **(Optional: If contributing from a fork)**
35+
- Edit `go.mod` and update the module path to match your fork. Save and commit.
36+
37+
3. **Organization UID**
38+
- All Exoscale Academy content is namespaced under the UID:
39+
```
40+
98e16360-a366-4b78-8e0a-031da07fdacb
41+
```
42+
43+
## Repository Structure
44+
45+
```
46+
layer5io-exoscale-academy/
47+
├── README.md
48+
├── LICENSE
49+
├── go.mod, go.sum
50+
├── hugo.yaml
51+
├── Makefile, flake.nix, flake.lock, package.json, postcss.config.js
52+
├── content/
53+
│ └── en/
54+
│ └── learning-paths/
55+
│ └── 98e16360-a366-4b78-8e0a-031da07fdacb/
56+
│ └── /
57+
│ └── /
58+
│ └── /
59+
│ └── content/
60+
│ └── .md
61+
├── static/
62+
│ └── 98e16360-a366-4b78-8e0a-031da07fdacb/
63+
│ └── images/
64+
├── layouts/
65+
│ └── shortcodes/
66+
│ └── 98e16360-a366-4b78-8e0a-031da07fdacb/
67+
│ └── custom-org-shortcode.html
68+
└── .github/
69+
└── ISSUE_TEMPLATE/, workflows/, config, etc.
70+
```
71+
> **Learning Path → Course → Chapter → Lesson** is the core structure.
72+
Each level uses `_index.md` and lessons use `.md` files with [Hugo frontmatter](https://gohugo.io/content-management/front-matter/).
73+
74+
## Content Authoring Workflow
75+
76+
1. **Create Content**
77+
78+
- Authoring takes place inside:
79+
```
80+
content/en/learning-paths/98e16360-a366-4b78-8e0a-031da07fdacb/
81+
```
82+
- Structure:
83+
```
84+
<learning-path>/
85+
<course>/
86+
<chapter>/
87+
content/
88+
lesson1.md
89+
lesson2.md
90+
```
91+
92+
- **Frontmatter Required** (example for any `_index.md` or lesson .md):
93+
94+
```yaml
95+
---
96+
title: "Title of Section or Lesson"
97+
description: "One-liner summary"
98+
weight: 10 # for menu order, lower numbers appear first
99+
---
100+
```
101+
102+
2. **Delete Example Content**
103+
- Remove any demo/example files not relevant to your new material.
104+
105+
3. **Organize Lessons**
106+
- Add new folders and markdown files for each learning path, course, chapter, and lesson.
107+
108+
## Managing Assets (Images & Videos)
109+
110+
Enhance your courses with images and rich visual content. For compatibility with the Layer5 Academy’s multi-tenant architecture, **do not use standard Markdown image links**. Use shortcodes as described below.
111+
112+
### How to Add an Image
113+
114+
1. Place your image (example: `exoscale-logo.png`) in the organization’s static directory:
115+
116+
```
117+
static/98e16360-a366-4b78-8e0a-031da07fdacb/images/exoscale-logo.png
118+
```
119+
120+
2. In lesson markdown, embed your image using the `usestatic` shortcode (path is relative to your org’s folder):
121+
122+
```markdown
123+
![Exoscale Logo]({{</* usestatic path="images/exoscale-logo.png" */>}})
124+
```
125+
126+
> When you build the site, this shortcode automatically resolves to a working, tenant-aware asset path.
127+
128+
### How to Add a Video
129+
130+
Embed videos in a visually distinct `card` using:
131+
132+
```markdown
133+
{{</* card title="Video: Example" */>}}
134+
<video width="100%" height="100%" controls>
135+
<source src="https://example.com/your-video.mp4" type="video/mp4">
136+
Your browser does not support the video tag.
137+
</video>
138+
{{</* /card */>}}
139+
```
140+
141+
> Always use these shortcodes for images and videos so assets remain portable, visible, and cloud-ready.
142+
143+
## Local Development
144+
145+
To preview your content locally, run:
146+
147+
```bash
148+
hugo server
149+
```
150+
151+
- Open the local URL displayed in your terminal browser.
152+
- Local preview uses plain styling; full Layer5 Cloud branding is applied on production.
153+
154+
## Deploying & Going Live
155+
156+
1. **Commit and push** your changes to a branch or `main`.
157+
2. **Contact Layer5** via [Slack](https://slack.layer5.io/), email, or by opening a GitHub issue.
158+
3. Provide your repository URL.
159+
4. Once reviewed, a Layer5 admin will synchronize your content to the [Layer5 Cloud Academy](https://cloud.layer5.io/academy/overview).
160+
161+
## Contributing
162+
163+
- See [Academy Docs](https://docs.layer5.io/cloud/academy) for best practices on creating and publishing learning paths, courses, chapters, and challenges.
164+
- Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for branching, committing, and PR workflow.
165+
- Review [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and [SECURITY.md](./SECURITY.md) prior to contributing.
166+
167+
## Site Framework
168+
169+
- **Stack:** Built with [Golang](https://golang.org/) and [Hugo](https://gohugo.io/), fully integrated with [Layer5 Cloud](https://cloud.layer5.io/academy/overview).
170+
- **Theme & Template:** Refer to [academy-theme](https://github.com/layer5io/academy-theme) and [academy-template](https://github.com/layer5io/academy-template) for advanced customization.
171+
172+
## License
173+
174+
Distributed under the [Apache 2.0 License](./LICENSE).
175+
176+
For questions or help, open a [GitHub Issue](https://github.com/layer5io/exoscale-academy/issues) or join the [Layer5 Slack Community](https://slack.layer5.io/).
177+
178+
**Happy Learning!**
179+
_The Layer5 & Exoscale Academy Team_

0 commit comments

Comments
 (0)