Skip to content

Commit 26bb2aa

Browse files
leecalcoteleecalcote
authored
Merge pull request #157 from layer5io/copilot/create-agents-md-file
Add agents.md documentation for GitHub Copilot
2 parents fde0e72 + 36454fd commit 26bb2aa

File tree

1 file changed

+202
-0
lines changed

1 file changed

+202
-0
lines changed

‎agents.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# GitHub Copilot Agents for Academy Theme
2+
3+
This document provides guidance for GitHub Copilot agents working on the
4+
Layer5 Academy Theme repository.
5+
6+
## Repository Overview
7+
8+
This repository contains a reusable Hugo theme module that powers Layer5
9+
Academy. It provides layouts, shortcodes, and partials to build educational
10+
content sites using the Hugo static site generator.
11+
12+
**Technology Stack:**
13+
14+
- Hugo (extended version 0.146.0+)
15+
- Node.js & npm
16+
- Go modules
17+
- PostCSS & Autoprefixer
18+
- Docsy theme as a base
19+
- Layer5 Sistent Design System
20+
21+
## Development Environment
22+
23+
### Prerequisites
24+
25+
- Go (latest version)
26+
- Node.js and npm
27+
- Hugo Extended (version 0.146.0 or later, as specified in hugo.yaml)
28+
29+
### Setup Commands
30+
31+
```bash
32+
# Install dependencies
33+
npm install
34+
35+
# Run the development server
36+
make site
37+
38+
# Build the site
39+
make build
40+
41+
# Clean cache and restart
42+
make clean
43+
```
44+
45+
## Project Structure
46+
47+
- `/layouts/` - Hugo layout templates
48+
- `/assets/` - CSS, JavaScript, and other static assets
49+
- `/archetypes/` - Content templates for different types of educational content
50+
(courses, modules, labs, tests, certifications)
51+
- `/static/` - Static files
52+
- `/i18n/` - Internationalization files
53+
- `hugo.yaml` - Main Hugo configuration
54+
- `package.json` - Node.js dependencies and build scripts
55+
56+
## Key Features
57+
58+
This theme supports several educational content types through archetypes:
59+
60+
- **Courses** - Top-level course containers
61+
- **Learning Paths** - Structured learning sequences
62+
- **Modules** - Course sections
63+
- **Labs** - Hands-on practice exercises
64+
- **Tests & Challenges** - Assessment components
65+
- **Certifications** - Credential tracking
66+
67+
## Development Guidelines
68+
69+
### Making Changes
70+
71+
1. **Local Development**: When developing this theme locally, link it to a Hugo
72+
site (like [academy-example](https://github.com/layer5io/academy-example))
73+
using a `replace` directive in the site's `go.mod` file:
74+
75+
```go
76+
replace github.com/layer5io/academy-theme => ../academy-theme
77+
```
78+
79+
2. **Testing**: Always test changes with an actual Academy site to ensure
80+
layouts and components work correctly.
81+
82+
3. **Code Style**:
83+
- Follow existing code patterns and conventions
84+
- Use meaningful commit messages
85+
- Keep changes minimal and focused
86+
87+
### Linting
88+
89+
To fix Markdown linting issues:
90+
91+
```bash
92+
make lint-fix
93+
```
94+
95+
This requires `markdownlint-cli2` (will be auto-installed if using npm).
96+
97+
## Common Tasks for Agents
98+
99+
### Adding New Layouts
100+
101+
- Review existing layouts in `/layouts/` for patterns
102+
- Ensure consistency with the Docsy base theme
103+
- Test with multiple content types
104+
105+
### Modifying Styles
106+
107+
- CSS/SCSS files are in `/assets/`
108+
- PostCSS is configured via `postcss.config.js`
109+
- Changes should be compatible with the theme's responsive design
110+
111+
### Design System Adherence
112+
113+
#### Layer5 Sistent Design System
114+
115+
This theme adheres to the [Layer5 Sistent Design
116+
System](https://github.com/layer5io/sistent), which provides consistent UI
117+
components, colors, typography, and behaviors across all Layer5 projects.
118+
119+
- **Color Palette**: Use colors defined in `assets/scss/_variables_project.scss`
120+
- Primary: `#00b39f` (teal/green)
121+
- Secondary: `#3C494F` (dark gray)
122+
- Refer to the Sistent design system for the complete color palette
123+
- **Typography**: Follow Qanelas Soft font family and typography scale
124+
- **Components**: Ensure UI components match Sistent design patterns
125+
- **Behaviors**: Interactive elements should follow Sistent interaction patterns
126+
- **Documentation**: [Sistent site](https://layer5.io/projects/sistent) provides
127+
detailed guidelines
128+
129+
When making style changes, always verify they align with the Sistent design
130+
system to maintain consistency across Layer5 properties.
131+
132+
### Creating New Archetypes
133+
134+
- Add new content type templates in `/archetypes/`
135+
- Follow the naming convention: `{type}.md`
136+
- Include appropriate front matter defaults
137+
138+
### Updating Dependencies
139+
140+
- Hugo modules: Update `hugo.yaml` and run `hugo mod get -u`
141+
- Node packages: Update `package.json` and run `npm install`
142+
- Always test after dependency updates
143+
144+
## Important Notes
145+
146+
### What NOT to Change
147+
148+
- Do not modify core Hugo/Docsy functionality unless absolutely necessary
149+
- Avoid breaking changes that would affect existing Academy sites using this
150+
theme
151+
- Do not commit `node_modules/`, `public/`, or `resources/` directories
152+
153+
### Security Considerations
154+
155+
- Report security vulnerabilities to <security-vulns-reports@layer5.io>
156+
- Never commit secrets or credentials
157+
- Review the [SECURITY.md](./SECURITY.md) file for full security policy
158+
159+
### Git Workflow
160+
161+
- Follow the git flow described in [CONTRIBUTING-gitflow.md](./CONTRIBUTING-gitflow.md)
162+
- Create descriptive pull request titles
163+
- Reference related issues in commits and PRs
164+
165+
## Testing Your Changes
166+
167+
Since this is a theme module, testing requires:
168+
169+
1. **Link to a test site**: Use the academy-example repository or create a test site
170+
2. **Verify layouts render correctly**: Check all content types (courses,
171+
modules, labs, etc.)
172+
3. **Test responsive design**: Ensure mobile and desktop views work
173+
4. **Validate navigation**: Menu, breadcrumbs, and links should function properly
174+
5. **Check build output**: Run `make build` to ensure no errors
175+
176+
## Resources
177+
178+
- **Layer5 Sistent Design System**: [Sistent](https://layer5.io/projects/sistent)
179+
| [GitHub](https://github.com/layer5io/sistent)
180+
- **Main Documentation**: [Layer5 Academy Docs](https://docs.layer5.io/cloud/academy/)
181+
- **Starter Template**: [academy-example](https://github.com/layer5io/academy-example)
182+
- **Hugo Documentation**: [gohugo.io](https://gohugo.io/)
183+
- **Docsy Theme**: [docsy.dev](https://www.docsy.dev/)
184+
- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)
185+
186+
## Getting Help
187+
188+
- Check existing issues: [GitHub Issues](https://github.com/layer5io/academy-theme/issues)
189+
- Review pull requests for examples
190+
- Consult the Layer5 community on Slack
191+
- Read the Hugo and Docsy documentation for theme development patterns
192+
193+
## Workflow Integration
194+
195+
This repository uses GitHub Actions for:
196+
197+
- Version bumping (`bump-academy-version.yml`)
198+
- Labeling and PR management
199+
- Slack notifications
200+
- Release drafting
201+
202+
Ensure your changes don't break CI/CD workflows.

0 commit comments

Comments
 (0)