Skip to content

Latest commit

 

History

History
223 lines (159 loc) · 9.19 KB

AGENTS.md

File metadata and controls

223 lines (159 loc) · 9.19 KB

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

This is the Masterpoint.io company website - a Hugo-based static site for an Infrastructure-as-Code (IaC) consulting firm specializing in Terraform, OpenTofu, Pulumi, and cloud infrastructure solutions. The site is deployed on Netlify with automatic builds from the Git repository.

Case Studies

When working on anything related to case studies, always reference docs/case-studies.md first. It documents the case-study architecture, layouts, shortcodes, front matter schema, styling decisions, and iteration workflow. Keep it updated — whenever you make a decision about case-study layout, shortcodes, visuals, or workflow, update that file before ending the session (and remove mentions of anything deleted from the codebase).

Videos

When adding video to a post or page, reference docs/videos.md first. It documents the loop-video shortcode, the ffmpeg encoding recipe, the lazy-load/play-on-view behavior, and the gotchas (single-line shortcode calls, the Defer.js conflict, the non-lazy poster). Keep it updated when the shortcode, encoding recipe, or behavior changes.

Careers / Job Postings

When working on anything related to hiring, job postings, or the /careers/ section, always reference docs/careers.md first. It documents the section architecture, job-post front matter schema, the Netlify application form, and the posting/closing workflow. Keep it updated whenever you change careers layouts, front matter, the form, or the workflow.

Essential Commands

Development

# Install Hugo Extended (required - regular Hugo won't work due to SCSS)
aqua install

# Run development server (auto-reload on changes)
hugo serve

# Build the site for production
hugo --gc --minify

# Create new content (blog posts use date-prefixed naming)
hugo new blog/$(date +%Y-%m-%d)-my-new-post.md
hugo new case-studies/client-name.md
# Job postings live in content/careers/ (see docs/careers.md)

# Lint and format code
trunk check
trunk fmt

Local Development

  • Server runs on: http://localhost:1313
  • Hugo Extended v0.145.0 is required (managed via Aqua)
  • No npm/yarn commands - this is a pure Hugo project
  • Trunk is used for linting (markdownlint, prettier, checkov, etc.)

Architecture Overview

Content Management

  • All content is in Markdown files under /content/
  • NetlifyCMS is configured for content editing (accessible at /admin/)
  • Front matter in Markdown files controls metadata and page behavior
  • Content types: blog posts, case studies, job postings (careers), services, team profiles, landing pages

Template System

/layouts/
├── _default/        # Default templates (list.html, single.html)
├── partials/        # Reusable components (header, footer, etc.)
├── shortcodes/      # Custom Hugo shortcodes
└── [content-type]/  # Type-specific templates (blog, services, etc.)

Styling Architecture

  • Bootstrap 5.1.3 provides the CSS framework
  • Custom SCSS in /assets/css/style.scss
  • Pre-minified JavaScript plugins in /assets/js/plugins.js
  • No build process for JS - uses static files

Key Configuration Files

  • config.yaml - Site configuration, menus, params
  • netlify.toml - Build settings, redirects, Hugo version
  • aqua.yaml - Manages Hugo Extended installation

Content Creation Patterns

Blog Posts

Every blog post must include date, the commented-out # date_modified line, and the standard callout exactly as shown below (unless the post has a custom callout).

Example blog post header:

---
visible: true
draft: false
title: "The Platform Engineering Way to Manage Google Workspace Users"
author: Weston Platter
date: 2025-07-17
# date_modified: 2026-xx-xx Be sure to use this if you've updated the post as this helps with SEO and index freshness
slug: platform-engineering-way-to-manage-google-workspace-users
description: "Migrate Google Workspace from ClickOps to Infrastructure as Code with our open source Terraform module. Includes design patterns and import examples."
tags: ["terraform", "google-workspace", "infrastructure-as-code", "automation"]
image: /img/updates/managing-googleworkspace-with-terraform/preview-3.png
callout: <p>👋 <b>If you're ready to take your infrastructure to the next level, we're here to help. We love to work together with engineering teams to help them build well-documented, scalable, automated IaC that make their jobs easier. <a href='/contact'>Get in touch!</a></p>
---

<CONTENT>

### Code Blocks

- **Always** open code blocks in blog posts with the copy/collapse attributes, e.g. ` ````markdown {copy=true collapse=true} ` (swap `markdown` for the block's language), and close them with four backticks. `layouts/_default/_markup/render-codeblock.html` turns `copy=true` into a Copy button and `collapse=true` into a collapsed block with a "Show more" toggle.
- Use four backticks rather than three so the block can contain triple-backtick fences of its own (common in prompts, skills, and READMEs).

### Custom Shortcodes

- `{{< button link="/path" text="CTA Text" >}}` - Call-to-action buttons
- `{{< buttonout link="https://external.com" text="External Link" >}}` - External buttons
- `{{< form formName="contact" >}}` - Contact forms
- `{{< testimonials >}}` - Client testimonials
- `{{< faqs >}}` - FAQ sections
- `{{< team >}}` - Team member displays
- `{{< services >}}` - Service listings
- `{{< process >}}` - Process steps
- `{{< supports >}}` - Support/technology logos
- `{{< client-logos >}}` - Client logo displays
- `{{< loop-video src="..." poster="..." width="..." height="..." alt="..." >}}` - Silent looping demo clip, lazy-loaded and played only in view (see [`docs/videos.md`](docs/videos.md))

## Code Quality & Linting

The project uses Trunk for code quality management with multiple linters:

- **Markdown**: markdownlint with custom config (`.markdownlint.yaml`)
- **YAML**: yamllint for configuration files
- **Security**: checkov for infrastructure security, gitleaks for secrets
- **Formatting**: prettier for consistent code style
- **Images**: oxipng for PNG optimization, svgo for SVG optimization

```bash
# Run all linters
trunk check

# Auto-fix issues where possible
trunk fmt

# Check specific files
trunk check path/to/file.md
```

## Important Development Notes

1. **Hugo Extended Required**: Regular Hugo will fail due to SCSS compilation needs
2. **Absolute URLs**: Use absolute paths in content (e.g., `/blog/` not `blog/`)
3. **Image Paths**: Reference images from `/img/` (maps to `/static/img/`)
4. **Draft Content**: Set `draft: true` in front matter to hide from production
5. **Menu Items**: Configure in `config.yaml` under `menu` section
6. **Redirects**: Add to `netlify.toml` (e.g., `/updates/*` → `/blog/*`)
7. **Blog Naming**: Use date-prefixed format: `YYYY-MM-DD-title.md`

## Pull Request & Commit Conventions

This repo uses [release-please](https://github.com/googleapis/release-please) semantics, enforced on every PR by the `lint` CI workflow's `action-semantic-pull-request` check. **The PR title** (not each individual commit) must start with a valid [Conventional Commits](https://www.conventionalcommits.org/) type prefix, or CI fails with "No release type found in pull request title":

```text
<type>(optional-scope): <description>
```

Valid types:

- `feat` - A new feature
- `fix` - A bug fix
- `docs` - Documentation only changes
- `style` - Changes that do not affect meaning (white-space, formatting, missing semi-colons, etc.)
- `refactor` - A code change that neither fixes a bug nor adds a feature
- `perf` - A code change that improves performance
- `test` - Adding or correcting tests
- `build` - Changes to the build system or external dependencies
- `ci` - Changes to CI configuration files and scripts
- `chore` - Other changes that don't modify src or test files (e.g. removing/updating team or content-only changes)

Examples: `feat: add case study for Acme Corp`, `fix: correct broken link in footer`, `chore: remove former team member`.

## Deployment Process

1. Push to Git repository (master branch)
2. Netlify automatically builds and deploys
3. Preview deployments created for pull requests
4. Production URL: https://masterpoint.io

## Common Tasks

### Add a New Blog Post

```bash
# Blog posts use date-prefixed naming (YYYY-MM-DD-title.md)
hugo new blog/$(date +%Y-%m-%d)-my-post-title.md
# Edit content/blog/YYYY-MM-DD-my-post-title.md
# Add banner image to static/img/blog/
# Set draft: false when ready
```

Update Team Member

  • Edit files in /content/team/
  • Update image in /static/img/team/
  • Follows pattern: firstname-lastname.md

Modify Site Navigation

  • Edit config.yaml → menu section
  • Supports nested menus and external links

Add Client Logo

  • Add logo to /static/img/clients/
  • Reference in /content/clients.md or relevant partial

Troubleshooting

  • SCSS Compilation Errors: Ensure Hugo Extended is installed via aqua install
  • Missing Content: Check draft status in front matter
  • 404 Errors: Verify URL paths are absolute (start with /)
  • Build Failures: Check Netlify logs, ensure Hugo version matches