Coding Agent Instructions for Layer5 Docs

AI Model Selection

IMPORTANT: When using GitHub Copilot, always select the most powerful AI model available (e.g., GPT-5.1 Codex, Gemini 3 Pro Claude 4.5, or the latest advanced model) to ensure the most comprehensive, most human-understandable documentation with examples, tips, notes, analogies and so on.

Project Overview

The Layer5 Docs website is a Hugo-based documentation site that serves as the primary documentation resource for Layer5 products, hosted at https://github.com/layer5io/docs and live at https://docs.layer5.io. It provides comprehensive documentation for Layer5 Cloud, Kanvas, and related products, offering tutorials, guides, and reference materials for users and contributors in the cloud native ecosystem.

Technology Stack

• Framework: Hugo (extended version with SCSS support)
• Theme: Docsy (Google's documentation theme)
• Language: Go templates, HTML, CSS/SCSS, JavaScript
• Content: Markdown with Hugo shortcodes
• Package Manager: npm
• Node Version: See .nvmrc
• Build System: Hugo CLI, Make

Core Principles

1. Minimal, Surgical Changes

• Make the smallest possible changes to accomplish the goal
• Never delete or modify working code unless absolutely necessary
• Focus on precise, targeted modifications rather than wholesale rewrites
• Preserve existing patterns and conventions unless explicitly changing them

2. Code Quality Standards

• Follow the existing code style and patterns in the repository
• Ensure proper indentation and formatting in templates and content
• Write clean, readable, self-documenting code with minimal comments unless necessary for complex logic
• Maintain accessibility standards (WCAG 2.1)

3. Testing and Validation

• Always validate changes work before considering them complete
• Build the site and verify rendered content: make build or hugo
• Run the site locally: make site or hugo server -D -F
• Test changes incrementally and iteratively

Project Structure

docs/
├── .github/                 # GitHub configuration and workflows
├── assets/                  # Site assets (CSS, JS, images)
├── charts/                  # Chart files
├── content/
│   └── en/                 # English content
│       ├── cloud/          # Layer5 Cloud documentation
│       ├── kanvas/         # Kanvas documentation
│       ├── contributing/   # Contribution guidelines
│       └── videos/         # Video content
├── data/                   # Hugo data files
├── layouts/                # Hugo templates and layouts
│   ├── _default/           # Default layouts
│   ├── partials/           # Partial templates
│   └── shortcodes/         # Custom shortcodes
├── static/                 # Static assets
├── hugo.toml               # Hugo configuration
├── package.json            # npm dependencies
├── Makefile                # Build automation
└── CONTRIBUTING.md         # Contribution guidelines

Development Workflow

1. Don't fork this repo.
2. Create a branch and pull request in this repo.
3. Don't mark your pull request as draft.

Setup

# Install dependencies (required for fresh clone)
make setup
# or
npm install

Development

# Start development server with drafts and future content
make site
# or
hugo server -D -F

Building

# Build for production
make build
# or
hugo

# Clean and rebuild
make clean

Docker Development

# Run with Docker (requires Docker Desktop 4.24+ or Docker Compose 2.22+)
make docker

Content Guidelines

Tone and Style

• Use a professional yet approachable tone
• Content should be clear, concise, and welcoming to both technical and non-technical audiences
• Align with Layer5's mission of empowering engineers to "expect more from their infrastructure"
• Use American English spelling and grammar

Markdown Content

• All documentation content is written in Markdown
• Place content files in appropriate directories under content/en/
• Include proper frontmatter with metadata:

---
title: "Page Title"
description: "Short description for SEO (150-160 chars)"
weight: 10  # Optional: controls ordering in navigation
---

Hugo Shortcodes

Use the project's custom shortcodes for enhanced content:

{{< alert type="success" title="Note" >}} Your Note {{< /alert >}}

Alert types:

• type="danger": Critical alerts (security-related or breaking changes)
• type="info": General informational content
• type="warning": Important warnings that need attention
• type="note": Neutral notes and tips
• type="success": Positive outcomes or confirmations

Image Guidelines

• Use the following syntax: ![alt text](/path/to/image.svg) or <img src="" alt="" />
• Always provide complete image paths for subpages
• Add data-modal="false" to prevent images from opening in a modal
• Always include descriptive alt text for accessibility and SEO

Content Restrictions

• No external images: Use local assets only
• No placeholder text: Provide complete, production-ready content
• No sensitive data: Never include API keys, credentials, or personal information
• Use proper capitalization: "Meshery" not "meshery", "Kanvas" not "canvas", "Layer5" not "layer5"

Template Guidelines

Hugo Templates

• Follow Go template syntax conventions
• Use partials for reusable template components
• Maintain consistent indentation in templates
• Use Hugo's built-in functions when possible

Styling

• SCSS files are located in assets/
• Follow existing CSS class naming conventions
• Ensure responsive design is maintained
• Use theme variables when possible

Accessibility

Required Standards: WCAG 2.1 Level AA

• Images: Always include descriptive alt text
• Interactive elements: Ensure keyboard navigation support
• ARIA labels: Use when semantic HTML is insufficient
• Color contrast: Maintain at least 4.5:1 ratio for text
• Semantic HTML: Use appropriate HTML5 elements

Git Workflow

Commit Messages

Follow Conventional Commits format:

<type>(<scope>): <subject>

Types:

• feat: New feature or content
• fix: Bug fix or correction
• docs: Documentation changes
• style: Formatting changes (no logic change)
• refactor: Code refactoring
• chore: Build process, tooling, dependencies

Examples:

feat(cloud): add workspace documentation
fix(kanvas): correct broken link in navigation
docs(contributing): update setup instructions

Pull Requests

• Submit all changes as PRs to the master branch
• Reference related issues in PR description
• Ensure CI checks pass before requesting review
• Sign-off commits with git commit -s

Branch Naming

Use descriptive, kebab-case names:

• feat/add-cloud-security-docs
• fix/navigation-broken-link
• docs/update-contributing-guide

Troubleshooting

Build Errors

• Check hugo.toml for configuration issues
• Clear cache: hugo --cleanDestinationDir
• Reinstall dependencies: rm -rf node_modules && npm install
• Verify Hugo extended version is installed

Content Issues

• Validate Markdown syntax and frontmatter
• Check for unclosed shortcodes
• Verify file paths are correct and case-sensitive

Development Server Issues

• Ensure Go is installed (required): go version
• Check Node.js version matches .nvmrc
• Verify Hugo extended version is installed

Security Best Practices

• Never commit secrets, API keys, or credentials
• Use environment variables for sensitive configuration
• Keep dependencies up to date
• Follow CSP headers and security configurations

Community and Resources

Documentation

• Layer5 Community Handbook: https://layer5.io/community/handbook
• Layer5 Documentation: https://docs.layer5.io
• Hugo Documentation: https://gohugo.io/documentation/

Getting Help

• Layer5 Slack: https://slack.layer5.io
• Discussion Forum: https://discuss.layer5.io
• GitHub Issues: https://github.com/layer5io/docs/issues

Code of Conduct

All contributions must adhere to the Layer5 Code of Conduct.

Summary Checklist for Contributions

Before submitting a PR, verify:

Content Quality

• Content is clear, accurate, and complete
• Proper frontmatter is included
• Images have descriptive alt text
• Links are valid and accessible
• Capitalization is correct (Meshery, Kanvas, Layer5)
• American English spelling and grammar

Technical Quality

• Build completes successfully (make build)
• Site renders correctly locally (make site)
• Changes are minimal and surgical
• No placeholder content or sensitive data
• Responsive design is maintained

Accessibility

• All images have alt text
• Proper heading hierarchy
• Keyboard navigation works
• Color contrast meets WCAG standards

Git

• Commit messages follow Conventional Commits
• Commits are signed off (git commit -s)
• PR references related issues

Example Documentation Page

---
title: "Getting Started with Layer5 Cloud"
description: "Learn how to set up your Layer5 Cloud account and start managing your cloud native infrastructure with ease."
weight: 1
---

# Getting Started with Layer5 Cloud

This guide walks you through setting up your Layer5 Cloud account and exploring key features.

## Prerequisites

Before you begin, ensure you have:
- A GitHub or Google account for authentication
- Basic familiarity with cloud native concepts

## Creating Your Account

1. Visit [Layer5 Cloud](https://cloud.layer5.io)
2. Click **Sign Up** and choose your authentication method
3. Complete your profile setup

{{< alert type="info" title="Tip" >}}
You can link multiple authentication providers to a single account.
{{< /alert >}}

## Next Steps

- [Explore Workspaces](/cloud/spaces/workspaces/)
- [Learn about Organizations](/cloud/identity/organizations/)
- [Set up API Tokens](/cloud/security/tokens/)

This document serves as the primary reference for GitHub Copilot when assisting with contributions to the Layer5 Documentation site. Always prioritize minimal changes, maintain existing patterns, and ensure quality through building and testing.