← Back to agents

AGENTS.md from layer5io/academy-theme

Repository
⭐ 30 starsLast commit Aug 10, 2026

GitHub Copilot Agents for Academy Theme

This document provides guidance for GitHub Copilot agents working on the Layer5 Academy Theme repository.

Repository Overview

This repository contains a reusable Hugo theme module that powers Layer5 Academy. It provides layouts, shortcodes, and partials to build educational content sites using the Hugo static site generator.

**Technology Stack:**

  • Hugo (extended version 0.146.0+)
  • Node.js & npm
  • Go modules
  • PostCSS & Autoprefixer
  • Docsy theme as a base
  • Layer5 Sistent Design System

Development Environment

Prerequisites

  • Go (latest version)
  • Node.js and npm
  • Hugo Extended (version 0.146.0 or later, as specified in hugo.yaml)

Setup Commands

```bash

Install dependencies

npm install

Run the development server

make site

Build the site

make build

Clean cache and restart

make clean ```

Project Structure

(courses, modules, labs, tests, certifications)

  • `/layouts/` - Hugo layout templates
  • `/assets/` - CSS, JavaScript, and other static assets
  • `/archetypes/` - Content templates for different types of educational content
  • `/static/` - Static files
  • `/i18n/` - Internationalization files
  • `hugo.yaml` - Main Hugo configuration
  • `package.json` - Node.js dependencies and build scripts

Key Features

This theme supports several educational content types through archetypes:

  • **Courses** - Top-level course containers
  • **Learning Paths** - Structured learning sequences
  • **Modules** - Course sections
  • **Labs** - Hands-on practice exercises
  • **Tests & Challenges** - Assessment components
  • **Certifications** - Credential tracking

Development Guidelines

Making Changes

1. **Local Development**: When developing this theme locally, link it to a Hugo site (like [academy-example](https://github.com/layer5io/academy-example)) using a `replace` directive in the site's `go.mod` file:

```go replace github.com/layer5io/academy-theme => ../academy-theme ```

2. **Testing**: Always test changes with an actual Academy site to ensure layouts and components work correctly.

3. **Code Style**:

  • Follow existing code patterns and conventions
  • Use meaningful commit messages
  • Keep changes minimal and focused

Linting

To fix Markdown linting issues:

```bash make lint-fix ```

This requires `markdownlint-cli2` (will be auto-installed if using npm).

Common Tasks for Agents

Adding New Layouts

  • Review existing layouts in `/layouts/` for patterns
  • Ensure consistency with the Docsy base theme
  • Test with multiple content types

Modifying Styles

  • CSS/SCSS files are in `/assets/`
  • PostCSS is configured via `postcss.config.js`
  • Changes should be compatible with the theme's responsive design

Design System Adherence

#### Layer5 Sistent Design System

This theme adheres to the [Layer5 Sistent Design System](https://github.com/layer5io/sistent), which provides consistent UI components, colors, typography, and behaviors across all Layer5 projects.

detailed guidelines

  • **Color Palette**: Use colors defined in `assets/scss/_variables_project.scss`
  • Primary: `#00b39f` (teal/green)
  • Secondary: `#3C494F` (dark gray)
  • Refer to the Sistent design system for the complete color palette
  • **Typography**: Follow Qanelas Soft font family and typography scale
  • **Components**: Ensure UI components match Sistent design patterns
  • **Behaviors**: Interactive elements should follow Sistent interaction patterns
  • **Documentation**: [Sistent site](https://layer5.io/projects/sistent) provides

When making style changes, always verify they align with the Sistent design system to maintain consistency across Layer5 properties.

Creating New Archetypes

  • Add new content type templates in `/archetypes/`
  • Follow the naming convention: `{type}.md`
  • Include appropriate front matter defaults

Updating Dependencies

  • Hugo modules: Update `hugo.yaml` and run `hugo mod get -u`
  • Node packages: Update `package.json` and run `npm install`
  • Always test after dependency updates

Important Notes

What NOT to Change

theme

  • Do not modify core Hugo/Docsy functionality unless absolutely necessary
  • Avoid breaking changes that would affect existing Academy sites using this
  • Do not commit `node_modules/`, `public/`, or `resources/` directories

Security Considerations

  • Report security vulnerabilities to <security-vulns-reports@layer5.io>
  • Never commit secrets or credentials
  • Review the [SECURITY.md](./SECURITY.md) file for full security policy

Git Workflow

  • Follow the git flow described in [CONTRIBUTING-gitflow.md](./CONTRIBUTING-gitflow.md)
  • Create descriptive pull request titles
  • Reference related issues in commits and PRs

Testing Your Changes

Since this is a theme module, testing requires:

1. **Link to a test site**: Use the academy-example repository or create a test site 2. **Verify layouts render correctly**: Check all content types (courses, modules, labs, etc.) 3. **Test responsive design**: Ensure mobile and desktop views work 4. **Validate navigation**: Menu, breadcrumbs, and links should function properly 5. **Check build output**: Run `make build` to ensure no errors

Resources

| [GitHub](https://github.com/layer5io/sistent)

  • **Layer5 Sistent Design System**: [Sistent](https://layer5.io/projects/sistent)
  • **Main Documentation**: [Layer5 Academy Docs](https://docs.layer5.io/cloud/academy/)
  • **Starter Template**: [academy-example](https://github.com/layer5io/academy-example)
  • **Hugo Documentation**: [gohugo.io](https://gohugo.io/)
  • **Docsy Theme**: [docsy.dev](https://www.docsy.dev/)
  • **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)

Getting Help

  • Check existing issues: [GitHub Issues](https://github.com/layer5io/academy-theme/issues)
  • Review pull requests for examples
  • Consult the Layer5 community on Slack
  • Read the Hugo and Docsy documentation for theme development patterns

Workflow Integration

This repository uses GitHub Actions for:

  • Version bumping (`bump-academy-version.yml`)
  • Labeling and PR management
  • Slack notifications
  • Release drafting

Ensure your changes don't break CI/CD workflows.