Development Guide

Development Guide

This guide explains how to develop and deploy the LATTS Internal Documentation site using Hugo and Cloudflare Pages.

Quick Start

Prerequisites

• Hugo Extended v0.148.2 or later
• Node.js v20 or later
• Git with modules enabled

Local Development

1. Clone and Initialize:

   git clone https://github.com/latts-ie/wiki-internal.git
   cd wiki-internal
   make install  # Install all dependencies
   

2. Start Development Server:

   make serve
   # Visit: http://localhost:1313
   

Available Make Commands

Our comprehensive Makefile provides all the automation you need:

Example Development Workflow

# Daily development workflow
make status          # Check everything is ready
make serve           # Start editing content
# ... make changes ...
make test           # Validate changes work
git add . && git commit -m "Update documentation"
git push            # Triggers automatic deployment

CI/CD Pipeline

The repository uses a comprehensive GitHub Actions workflow in .github/workflows/deploy.yml:

Pipeline Jobs

1. 🧪 Quality Checks

   • Hugo configuration validation
   • Markdown linting (optional)
   • Link checking (optional)

2. 🔨 Build & Test

   • Install dependencies (Hugo modules + npm)
   • Build site with optimizations
   • Validate generated HTML
   • Check LATTS branding presence

3. 🚀 Deploy

   • Deploy to Cloudflare Pages
   • Update preview URLs in PR comments
   • Performance monitoring

Deployment Speed: Changes go live in ~2-3 minutes after merge.

Modern Hugo Setup

This project uses Hugo Modules (not git submodules) for modern dependency management:

Key Features

• Hugo Modules: Modern dependency management
• PostCSS Processing: Optimized CSS with autoprefixer
• Git Integration: Direct edit links on every page
• Offline Search: Fast client-side search indexing
• Responsive Design: Mobile-first, accessible interface

Technology Stack

Content Management

Adding New Content

1. Create New Page:

   hugo new docs/section/new-page.md
   

2. Edit Front Matter:

   ---
   title: "Page Title"
   linkTitle: "Short Title"
   weight: 10
   description: "Page description"
   ---
   

3. Test Locally:

   make serve
   

Content Guidelines

• Clarity: Use simple, direct language
• Structure: Follow existing page templates and organization
• Accuracy: Test all commands and procedures
• Completeness: Include troubleshooting and “next steps”
• Screenshots: Add visual guides for UI-based processes

Performance Optimization

Build Performance

• Build Time: < 3 seconds for full site rebuild
• Dependencies: Cached Hugo modules and npm packages
• Incremental Builds: Only changed content rebuilds locally

Runtime Performance

• Page Load: < 1 second globally via Cloudflare CDN
• First Contentful Paint: < 0.8 seconds average
• Lighthouse Score: 95+ (Performance, Accessibility, SEO)
• Mobile Optimized: Responsive design with touch-friendly navigation

Caching Strategy

HTML pages:     1 hour (frequent updates)
CSS/JS assets:  1 year (content-hashed filenames)  
Images:         1 year (automatic WebP conversion)
Font files:     1 year (WOFF2 with font-display: swap)

Troubleshooting

Common Issues

Build Fails - Missing Dependencies:

make clean           # Clear build artifacts
make install         # Reinstall dependencies  
make status          # Verify Hugo Extended is installed

Deployment Failing:

# Check GitHub repository secrets are configured:
# - CLOUDFLARE_API_TOKEN
# - CLOUDFLARE_ACCOUNT_ID

Content Not Updating:

# Verify local development
make serve           # Check content appears locally
make test           # Ensure no validation errors

Debug Commands

make status         # Complete health check
hugo config         # Verify Hugo configuration
hugo server --debug # Detailed development server logs

Getting Help

1. Quick Issues: Check make status for common problems
2. Build Problems: Review GitHub Actions logs in repository
3. Content Questions: Create issue with documentation label
4. Technical Support: Contact LATTS development team

Contributing

Content Contribution Workflow

1. Find what to improve: Browse documentation or check GitHub issues
2. Edit content: Use “Edit this page” links or clone repository
3. Preview changes: Run make serve to test locally
4. Submit PR: Create pull request with clear description
5. Team review: Automated testing + peer review process
6. Auto-deploy: Approved changes go live automatically

Development Guidelines

• Test locally: Always run make test before submitting
• Follow standards: Check existing content patterns
• Documentation: Update README for new features or changes
• Performance: Optimize images and minimize dependencies

All contributions are reviewed for:

• Content accuracy and clarity
• Proper Hugo formatting
• Mobile responsiveness
• Link validation
• Security best practices