website-and-documentation/README-developer.md

Developer Guide - IPCEI-CIS Developer Framework

🚀 Quick Start

Prerequisites

Install Devbox:

curl -fsSL https://get.jetify.com/devbox | bash

Setup

1. Clone the repository
2. Install dependencies:

task deps:install

3. Start devbox shell:

devbox shell

Devbox automatically installs all required tools:

• Hugo (v0.151.0+extended)
• Go (v1.25.1)
• Node.js (v24.10.0)
• Dart Sass
• htmltest
• go-task

Note: For content contributors, see README-technicalWriter.md for a simplified guide.

📚 Technology Stack

Hugo (v0.151.0+extended)

Hugo is a fast static site generator. This project uses Hugo in extended mode with:

• Docsy Theme (v0.12.0) - Documentation theme with responsive design
• Bootstrap 5.3.8 - UI framework
• PostCSS - CSS processing

Docsy Theme

Docsy is a Hugo theme optimized for technical documentation:

• Multi-language support
• Search functionality
• Navigation menu system
• Code syntax highlighting
• Responsive design

Key directories:

• content/en/ - English content (Markdown files)
• layouts/ - Custom layout overrides
• assets/scss/ - Custom styles
• static/ - Static assets (images, etc.)

LikeC4 (v1.43.0)

LikeC4 is used for interactive architecture diagrams:

• C4 model-based architecture visualization
• Web Components for embedding diagrams
• Real-time preview during development

Architecture models:

• resources/edp-likec4/ - Platform architecture models
• resources/doc-likec4/ - Documentation platform models

LikeC4 tasks available:

• task likec4:generate - Generate web components
• task likec4:validate - Validate C4 models
• task likec4:update - Update LikeC4 version

Task (Taskfile)

Task is a task runner / build tool that replaces Makefiles. It uses Taskfile.yml for defining tasks.

🛠️ Development Workflow

Using Task (Recommended)

View all available tasks:

task
# or
task --list

Common tasks:

Development

task serve              # Start Hugo dev server (http://localhost:1313)
task build              # Build production site
task build:dev          # Build development site
task clean              # Clean build artifacts

Testing

task test               # Run all tests
task test:quick         # Run quick tests (without link checking)
task test:build         # Test if Hugo builds successfully
task test:markdown      # Lint Markdown files
task test:html          # Validate HTML output
task test:links         # Check all links (internal & external)

Dependencies

task deps:install       # Install all dependencies
task deps:update        # Update all dependencies

LikeC4

task likec4:generate    # Generate web components from C4 models
task likec4:validate    # Validate C4 model syntax
task likec4:update      # Update LikeC4 to latest version

Build & Test OCI Image

task build:oci-image    # Build Docker/OCI image
task test:oci-image     # Build and test image

CI/CD

task ci                 # Run full CI pipeline locally

🧪 Testing

This project uses multiple automated tests for quality assurance.

Test Configuration Files

• .htmltest.yml - Link checker configuration
• .htmlvalidate.json - HTML validation rules
• .markdownlint.json - Markdown linting rules

CI/CD Integration

GitHub Actions runs these tests automatically on every push/PR via .github/workflows/test.yml.

Local Development Workflow

Before commit:

task test:quick

Before push:

task test

🐳 Docker / Container Build

Version Management

All tool versions are defined in .env.versions as the single source of truth:

NODE_VERSION=24.10.0
GO_VERSION=1.25.1
HUGO_VERSION=0.151.0

These versions are used in:

• devbox.json - Local development (manual sync required)
• Dockerfile - Build arguments with defaults
• .github/workflows/ci.yaml - CI/CD pipeline (automatic)

Updating versions:

1. Edit .env.versions
2. Manually sync devbox.json:

   {
     "packages": [
       "hugo@0.151.0",
       "go@1.25.1",
       "nodejs@24.10.0"
     ]
   }
   

3. Rebuild: devbox shell --refresh

Local Build

Using Task (recommended):

task build:oci-image    # Build OCI image
task test:oci-image     # Build and test

This automatically loads versions from .env.versions and tags with latest and git commit hash.

Helper script for manual builds:

source scripts/get-versions.sh
# Shows Docker build command with correct versions

Manual build:

docker build --network=host \
  --build-arg NODE_VERSION=24.10.0 \
  --build-arg GO_VERSION=1.25.1 \
  --build-arg HUGO_VERSION=0.151.0 \
  -t ipceicis-developerframework:latest .

Test the image:

docker run -d -p 8080:80 --name hugo-test ipceicis-developerframework:latest
curl http://localhost:8080
docker stop hugo-test && docker rm hugo-test

Image Structure

• Build Stage: Node.js base, installs Go and Hugo
• Runtime Stage: nginx:alpine serves static content (~50MB)

Build process:

1. Install npm dependencies
2. Download Hugo modules
3. Build static site (hugo --gc --minify)
4. Copy to nginx container

CI/CD Pipeline

.github/workflows/ci.yaml automatically:

1. Extracts versions from devbox environment
2. Builds multi-arch images (amd64 + arm64)
3. Pushes to container registry

Required GitHub Secrets:

• PACKAGES_USER - Registry username
• PACKAGES_TOKEN - Registry token/password

CI/CD

task ci                 # Run full CI pipeline locally

Using NPM Scripts (Alternative)

If you prefer NPM:

npm test                # All tests
npm run test:quick      # Quick tests
npm run test:build      # Build test
npm run test:markdown   # Markdown linting
npm run test:html       # HTML validation
npm run test:links      # Link checking

Using Hugo Directly

# Development server
hugo server

# Production build
hugo --gc --minify

# Check version
hugo version

📁 Project Structure

.
├── content/            # Content files (Markdown)
│   └── en/            # English content
│       ├── docs/      # Documentation
│       └── blog/      # Blog posts
├── resources/         # LikeC4 architecture models
│   ├── edp-likec4/   # Platform architecture (C4 models)
│   └── doc-likec4/   # Documentation platform architecture
├── layouts/           # Custom HTML templates
│   └── shortcodes/   # Custom shortcodes (e.g., likec4-view)
├── static/            # Static files
│   └── js/           # JavaScript (LikeC4 webcomponents)
├── assets/            # Assets (SCSS, images)
├── public/            # Generated site (not in Git)
├── hugo.toml          # Hugo configuration
├── go.mod             # Hugo modules (Docsy theme)
├── Taskfile.yml       # Task definitions
├── package.json       # NPM dependencies & scripts
├── devbox.json        # Devbox configuration
├── .env.versions      # Version definitions (SSOT)
├── Dockerfile         # Multi-stage container build
├── README.md          # Main README
├── README-developer.md # This file
├── README-technicalWriter.md # Guide for content contributors
├── README-likec4.md   # LikeC4 architecture modeling guide
└── RELEASE.md         # Release process documentation

📝 Content Creation

Creating New Pages

# Using Hugo
hugo new docs/concepts/my-page.md
hugo new blog/my-post.md

# Or create manually in content/en/

Front Matter

Every content file needs front matter:

---
title: "My Page Title"
description: "Page description"
date: 2025-10-23
weight: 10  # Order in navigation
---

Your content here...

Using Docsy Shortcodes

Docsy provides helpful shortcodes:

Tabbed Panes

{{</* tabpane */>}}
  {{</* tab "Tab 1" */>}}
  Content for tab 1
  {{</* /tab */>}}
  {{</* tab "Tab 2" */>}}
  Content for tab 2
  {{</* /tab */>}}
{{</* /tabpane */>}}

Code Blocks

{{</* code lang="yaml" */>}}
key: value
{{</* /code */>}}

Alerts

{{</* alert title="Note" */>}}
Important information
{{</* /alert */>}}

LikeC4 Architecture Diagrams

{{</* likec4-view view="overview" project="architecture" title="System Overview" */>}}

Parameters:

• view - View ID from C4 model
• project - "architecture" or "documentation-platform"
• title - Optional custom title

See README-technicalWriter.md for detailed LikeC4 workflow.

🧪 Testing

See TESTING.md for detailed testing documentation.

Quick reference:

• task test - Run all tests before committing
• task test:quick - Fast checks during development
• Tests run automatically on GitHub Actions for PRs

🔧 Configuration

Hugo Configuration (hugo.toml)

Main settings:

• baseURL - Site URL
• title - Site title
• defaultContentLanguage - Default language
• Module imports (Docsy theme)

Docsy Configuration

Docsy-specific settings in hugo.toml:

[params]
github_repo = "your-repo"
github_branch = "main"

Devbox Configuration (devbox.json)

Defines all development tools and their versions.

Update tools:

devbox update          # Update all packages
task deps:update       # Update all dependencies (devbox + npm + hugo modules)

🎨 Styling

Custom styles in assets/scss/_variables_project.scss:

// Override Bootstrap/Docsy variables
$primary: #your-color;

Hugo will process SCSS automatically with PostCSS and Autoprefixer.

🌐 Multi-Language Support

Add new language:

1. Create content/<lang>/ directory
2. Add language config in hugo.toml:

[languages.<lang>]
languageName = "Language Name"
weight = 2

🐛 Troubleshooting

"Module not found" errors

hugo mod get -u
hugo mod tidy

PostCSS errors

npm install

Build errors

task clean
task build

Devbox issues

devbox update
devbox shell --refresh

📚 Resources

• Hugo Documentation
• Docsy Documentation
• LikeC4 Documentation
• Taskfile Documentation
• Devbox Documentation

Project-specific guides:

• README-technicalWriter.md - Content contributor guide
• TESTING.md - Detailed testing documentation
• DOCUMENTOR-GUIDE.md - Quick reference for technicalWriters

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Run tests: task test
4. Commit with semantic messages:
   • feat(scope): add new feature
   • fix(scope): fix bug
   • docs(scope): update documentation
   • test(scope): add tests
   • chore(scope): maintenance
5. Push and create pull request

📦 Deployment

Build for production:

task build

Output will be in public/ directory, ready for deployment.