Skip to content

agents.md

Latest commit

 

History

History
202 lines (142 loc) · 6.06 KB

agents.md

File metadata and controls

202 lines (142 loc) · 6.06 KB

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

# Install dependencies
npm install

# Run the development server
make site

# Build the site
make build

# Clean cache and restart
make clean

Project Structure

  • /layouts/ - Hugo layout templates
  • /assets/ - CSS, JavaScript, and other static assets
  • /archetypes/ - Content templates for different types of educational content (courses, modules, labs, tests, certifications)
  • /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) using a replace directive in the site's go.mod file:

    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:

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, which provides consistent UI components, colors, typography, and behaviors across all Layer5 projects.

  • 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 provides detailed guidelines

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

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

Security Considerations

Git Workflow

  • Follow the git flow described in 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

Getting Help

  • Check existing issues: GitHub 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.