This file provides guidance to AI coding agents when working with code in this repository.
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.
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).
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.
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.
# 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- 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.)
- 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
/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.)
- 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
config.yaml- Site configuration, menus, paramsnetlify.toml- Build settings, redirects, Hugo versionaqua.yaml- Manages Hugo Extended installation
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
```- Edit files in
/content/team/ - Update image in
/static/img/team/ - Follows pattern:
firstname-lastname.md
- Edit
config.yaml→menusection - Supports nested menus and external links
- Add logo to
/static/img/clients/ - Reference in
/content/clients.mdor relevant partial
- SCSS Compilation Errors: Ensure Hugo Extended is installed via
aqua install - Missing Content: Check
draftstatus in front matter - 404 Errors: Verify URL paths are absolute (start with
/) - Build Failures: Check Netlify logs, ensure Hugo version matches