Layer5 Academy - Content Starter Template

This repository offers a starter template for creating your own, dedicated academy on the Layer5 Academy platform. This repository provides the necessary file structure and a working example to help you get started quickly. The guide below offers a quick start to setting up your own content repository, creating curricula, and previewing your academy locally.

---

For in-depth tutorials and customization examples, see the Layer5 Academy docs.

---

Prerequisites

Before you begin, ensure you have the following installed on your system: 1. Go (use the version required by the root go.mod file) 2. Hugo (extended version, minimum 0.146.0 as defined in hugo.yaml)

Getting Started

Follow these steps to create your own learning path using this template.

1. Fork & Clone the Repository

First, create a copy of this repository under your own GitHub account. - Fork this academy-example repository. - Clone your forked repository:

# Replace <your-username> with your GitHub username
     git clone https://github.com/<your-username>/academy-example.git
     cd academy-example

2. Update the Go Module Path

- Open the go.mod file at the root of the project. - Change the first line from:

module github.com/layer5io/academy-example

- To match your repository's path:

module github.com/<your-username>/academy-example

- Save the file, then commit and push the change.

3. Configure Your Organization Directories

The Academy platform uses an Organization UID to keep content separate and secure. You must get this ID from the Layer5 CLoud before proceeding. Once you have your UID, rename the placeholder directories: - Rename content/learning-paths/your-org-uid to content/learning-paths/<your-organization-uid> - Rename static/your-org-uuid to static/<your-organization-uid> - Rename layouts/shortcodes/your-org-uuid to layouts/shortcodes/<your-organization-uid>

4. Add Your Content

Now you're ready to create your learning path. The structure is: Learning Path → Course → Chapter → Lesson. A high-level view of the structure looks like this:

content/
   └── learning-paths/
       ├── _index.md
       └── <your-organization-uid>/
           └── <your-learning-path>/
               ├── _index.md
               └── <your-course-1>/
               └── <your-course-2>/
                   ├── _index.md
                   └── content/
                       └── your-lesson-1.md
                       └── your-lesson-2.md

- Delete the example content inside content/learning-paths/<your-organization-uid>/. - Create your folder structure following the example's hierarchy. - Add your lessons as Markdown (.md) files inside the content directory of a course. - Use frontmatter at the top of your _index.md and lesson files to define titles, descriptions, and weights.

Add Assessments

Assessment files use the Academy test layout and define their questions in Markdown frontmatter. Use short, stable IDs for questions and options; question IDs must be unique within one assessment, and option IDs must be unique within one question. The Academy theme converts these author-facing IDs into deterministic UUIDs in the generated JSON consumed by Layer5 Cloud.

---
 title: "Assessment Example"
 id: "assessment-example"
 type: "test"
 layout: "test"
 passPercentage: 70
 maxAttempts: 3
 timeLimit: 30
 numberOfQuestions: 1
 questions:
   - id: "q1"
     text: "Academy content is authored in Markdown."
     type: "true-false"
     marks: 1
     options:
       - id: "true"
         text: "True"
         isCorrect: true
       - id: "false"
         text: "False"
 ---

5. Add Assets (Images & Videos)

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. How to Add an Image

• Place your image file (e.g., hugo-logo.png) in your scoped static directory:

static/<your-organization-uid>/images/hugo-logo.png

• In your lesson-1.md file, embed the image using the usestatic shortcode. The path is relative to your scoped static folder:

Then the system will automatically convert this into the correct URL when building the site. How to Add a Video

{{</* 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.
 </video>
 {{</ /card />}}

6. Local Development

This project includes a Makefile with helper targets to simplify local development and maintenance. Use the commands below as a quick reference.

# Install necessary tools and modules
 make setup
 
 
Start the local Hugo development server
 make site
 
 
Build the site for local consumption
 make build
 
 
Build the preview site with configured base URL
 make build-preview
 
 
Build production site output (CI)
 make build-production
 
 
Clean the Hugo cache and restart local setup
 make clean
 
 
Fix Markdown linting issues
 make lint-fix
 
 
Verify Go is installed before starting the local site
 make check-go
 
 
Update the academy-theme package version
 make theme-update

To preview your content locally, you can also run the Hugo server directly from the project root:

hugo server

This will start a local server. You can view your content and check for formatting issues before publishing.

The local preview uses basic styling. Full Academy branding and styles will be applied after your content is integrated into the cloud platform.

7. Going Live

Once your content is complete and tested locally:

• Push all your changes to your forked repository on GitHub.

• Connect the Layer5 Team via Slack, email, or by opening a GitHub issue.

• Provide the URL to your content repository.

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.

Community & Contributions

We warmly welcome contributions of all kinds! Whether you're improving documentation, enhancing the example academy, fixing bugs, or proposing new features, your contributions help make the Academy ecosystem better for everyone. Before getting started, please review this project's [contributing guidelines][contrib]. Contributors are expected to follow the CNCF Code of Conduct.

Helpful Resources

• 📚 Academy [documentation][docs], [example][example], and [theme][theme]

• 🎨 Layer5 [designs and wireframes][figma] in Figma ([open invite][figma-invite])

• 👥 Connect through the [Layer5 Discussion Forum][forum] and [Layer5 Community Slack][slack]

✔️ Join the Layer5 Slack Community.
✔️ Discuss in the Community Forum.
✔️ Explore the Community Handbook.
✔️ Start with the Newcomer's Guide.

[contrib]: ./CONTRIBUTING.md [docs]: https://docs.layer5.io/cloud/academy/ [example]: https://github.com/layer5io/academy-example/ [theme]: https://github.com/layer5io/academy-theme/ [figma]: https://www.figma.com/file/5ZwEkSJwUPitURD59YHMEN/Layer5-Designs [figma-invite]: https://www.figma.com/team_invite/redeem/GvB8SudhEOoq3JOvoLaoMs [forum]: https://discuss.layer5.io [slack]: https://slack.layer5.io