Skip to content

Commit 93ede2a

Browse files
zihanKuangzihanKuang
authored
Merge pull request #783 from Vincamine/w-mkd-tml
Add Advanced Content Features Documentation for Academy
2 parents 0d9bfcb + 9138984 commit 93ede2a

4 files changed

Lines changed: 134 additions & 3 deletions

File tree

‎content/en/cloud/academy/creating-content/extending-the-academy/index.md‎

Lines changed: 116 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,121 @@ For example, a **Learning Path** named **"Mastering Kubernetes"** might contain:
5252
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/).
5353
{{< /alert >}}
5454

55+
### Advanced Content Features
56+
57+
Create custom Hugo shortcodes, mix HTML with Markdown, and add custom CSS styling to enhance your Academy content.
58+
59+
#### Content Format Support
60+
61+
The Academy platform supports **Markdown + HTML mixing** and **custom CSS styling**.
62+
63+
##### HTML + Markdown Integration
64+
65+
Combine Markdown syntax with HTML elements in the same file:
66+
67+
```markdown
68+
## Markdown Heading
69+
70+
This is **bold** text in markdown.
71+
72+
<div style="background: #000000ff; padding: 20px;">
73+
<h3>HTML Section</h3>
74+
<p>This is HTML with **markdown** inside.</p>
75+
</div>
76+
```
77+
78+
##### Custom CSS Support
79+
80+
The platform supports CSS through multiple methods:
81+
82+
1. **Inline CSS** (as shown above)
83+
2. **CSS in shortcodes** (demonstrated below)
84+
3. **CSS classes** in HTML elements
85+
86+
{{< styled-callout title="Live Example" >}}
87+
This example demonstrates custom CSS styling within the Academy platform. The styling includes custom colors, padding, borders, and typography.
88+
{{< /styled-callout >}}
89+
90+
When properly rendered, you will see:
91+
- Markdown formatting (bold, italic, links) processed within HTML elements
92+
- Custom CSS styles applied (colors, spacing, borders)
93+
- Seamless integration without layout conflicts
94+
- Responsive behavior across different screen sizes
95+
96+
#### Creating Custom Shortcodes
97+
98+
Custom shortcodes are reusable components that enhance Academy content. They function as templates that accept parameters and generate HTML output.
99+
100+
##### Basic Shortcode
101+
102+
**Step 1:** Create the shortcode file in your organization's directory:
103+
```
104+
layouts/shortcodes/<your-organization-uuid>/custom-org-shortcode.html
105+
```
106+
107+
**Step 2:** Define the shortcode template:
108+
```html
109+
{{ $names := .Get "names" }}
110+
<div class="custom shortcode">
111+
{{ $names }}
112+
Hey! This is a custom shortcode
113+
</div>
114+
```
115+
116+
**Step 3:** Use the shortcode in your content:
117+
```markdown
118+
{{< custom-org-shortcode names="Alex, Bob, Charely" >}}
119+
```
120+
121+
**How it works:**
122+
- `{{ .Get "names" }}` retrieves the "names" parameter
123+
- The shortcode outputs: "Alex, Bob, Charely Hey! This is a custom shortcode"
124+
- You can reuse this shortcode throughout your Academy content
125+
126+
##### Shortcode with CSS
127+
128+
Add CSS styling to make shortcodes visually appealing.
129+
130+
**Example:** `layouts/shortcodes/<your-org-uuid>/styled-callout.html`
131+
```html
132+
<style>
133+
.custom-callout {
134+
padding: 1rem;
135+
margin: 1rem 0;
136+
border-radius: 4px;
137+
border-left: 4px solid #007bff;
138+
background: #f8f9fa;
139+
}
140+
</style>
141+
<div class="custom-callout">
142+
<strong>{{ .Get "title" | default "Note" }}:</strong> {{ .Inner }}
143+
</div>
144+
```
145+
146+
**Usage:**
147+
```markdown
148+
{{</* styled-callout title="Custom CSS Example" */>}}
149+
This is a styled callout with custom CSS.
150+
{{</* /styled-callout */>}}
151+
```
152+
153+
**Result:**
154+
{{< styled-callout title="Custom CSS Example" >}}
155+
This is a styled callout with custom CSS.
156+
{{< /styled-callout >}}
157+
158+
**How CSS works in shortcodes:**
159+
- `<style>` tags define the visual appearance
160+
- `.custom-callout` creates a CSS class for styling
161+
- The shortcode applies padding, margins, colors, and borders
162+
- `{{ .Inner }}` displays the content between opening and closing shortcode tags
163+
164+
##### Advanced Hugo Features
165+
166+
{{< alert type="info" title="Email Customization" >}}
167+
The Layer5 Academy platform supports all Hugo shortcode features. For more advanced functionality, see the [Hugo documentation](https://gohugo.io/content-management/shortcodes/).
168+
{{< /alert >}}
169+
55170
### Branded Email Communications
56171

57172
When using the Academy with [white-labeling](/cloud/self-hosted/white-labeling) enabled, all system-generated emails (badge awards, certificate awards, challenge registrations) automatically reflect your organization's branding.
@@ -84,5 +199,4 @@ When users click the badge, they will go to the details in the Academy:
84199

85200
{{< alert type="info" title="Email Customization" >}}
86201
Email templates automatically incorporate your organization's logo and primary brand color as configured in your [Layer5 Cloud Organization Settings](https://cloud.layer5.io/identity/organizations). Custom email templates can be provided for Enterprise customers with specific branding requirements.
87-
{{< /alert >}}
88-
202+
{{< /alert >}}

‎content/en/cloud/academy/platform-development/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ This repository is the "skin" for the entire Academy. It controls the website's
2626

2727
Content repositories automatically import this theme as a Go Module. As a content creator, you do not need to fork or clone this repository; your academy will use these styles by default.
2828

29-
> Currently, we only support customizing shortcodes in your content repository, not full theme customization.
29+
> Currently, we only support customizing shortcodes in your content repository, not full theme customization. For requests regarding new archetypes, layouts, or theme enhancements, please open an issue in the [academy-theme repository](https://github.com/layer5io/academy-theme/issues).
3030
3131
### [academy-example](https://github.com/layer5io/academy-example)
3232

‎layouts/shortcodes/custom-org-shortcode.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{{ $names := .Get "names" }}
2+
<div class="custom shortcode">
3+
{{ $names }}
4+
Hey! This is a custom shortcode
5+
</div>

‎layouts/shortcodes/styled-callout.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<style>
2+
.custom-callout {
3+
padding: 1rem;
4+
margin: 1rem 0;
5+
border-radius: 8px;
6+
border-left: 20px solid #007bff;
7+
background: #39393a;
8+
}
9+
</style>
10+
<div class="custom-callout">
11+
<strong>{{ .Get "title" | default "Note" }}:</strong> {{ .Inner }}
12+
</div>

0 commit comments

Comments
 (0)