# Developer Guide - IPCEI-CIS Developer Framework

## 🚀 Quick Start

### Prerequisites

Install [Devbox](https://www.jetify.com/devbox/):
```bash
curl -fsSL https://get.jetify.com/devbox | bash
```

### Setup

1. Clone the repository
2. Install dependencies:
```bash
task deps:install
```
3. Start devbox shell:
```bash
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-documentor.md](./README-documentor.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:
```bash
task
# or
task --list
```

Common tasks:

#### Development
```bash
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
```bash
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
```bash
task deps:install       # Install all dependencies
task deps:update        # Update all dependencies
```

#### LikeC4
```bash
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
```bash
task build:oci-image    # Build Docker/OCI image
task test:oci-image     # Build and test image
```

#### CI/CD
```bash
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:**
```bash
task test:quick
```

**Before push:**
```bash
task test
```

## 🐳 Docker / Container Build

### Version Management

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

```bash
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`:
   ```json
   {
     "packages": [
       "hugo@0.151.0",
       "go@1.25.1",
       "nodejs@24.10.0"
     ]
   }
   ```
3. Rebuild: `devbox shell --refresh`

### Local Build

**Using Task (recommended):**

```bash
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:**

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

**Manual build:**

```bash
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:**

```bash
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
```bash
task ci                 # Run full CI pipeline locally
```

### Using NPM Scripts (Alternative)

If you prefer NPM:
```bash
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

```bash
# 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-documentor.md # Guide for content contributors
├── README-likec4.md   # LikeC4 architecture modeling guide
└── RELEASE.md         # Release process documentation
```

## 📝 Content Creation

### Creating New Pages

```bash
# 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:

```yaml
---
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
```markdown
{{</* tabpane */>}}
  {{</* tab "Tab 1" */>}}
  Content for tab 1
  {{</* /tab */>}}
  {{</* tab "Tab 2" */>}}
  Content for tab 2
  {{</* /tab */>}}
{{</* /tabpane */>}}
```

#### Code Blocks
```markdown
{{</* code lang="yaml" */>}}
key: value
{{</* /code */>}}
```

#### Alerts
```markdown
{{</* alert title="Note" */>}}
Important information
{{</* /alert */>}}
```

#### LikeC4 Architecture Diagrams
```markdown
{{</* 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-documentor.md](./README-documentor.md) for detailed LikeC4 workflow.

## 🧪 Testing

See [TESTING.md](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`:
```toml
[params]
github_repo = "your-repo"
github_branch = "main"
```

### Devbox Configuration (`devbox.json`)

Defines all development tools and their versions. 

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

## 🎨 Styling

Custom styles in `assets/scss/_variables_project.scss`:
```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`:
```toml
[languages.<lang>]
languageName = "Language Name"
weight = 2
```

## 🐛 Troubleshooting

### "Module not found" errors
```bash
hugo mod get -u
hugo mod tidy
```

### PostCSS errors
```bash
npm install
```

### Build errors
```bash
task clean
task build
```

### Devbox issues
```bash
devbox update
devbox shell --refresh
```

## 📚 Resources

- [Hugo Documentation](https://gohugo.io/documentation/)
- [Docsy Documentation](https://www.docsy.dev/docs/)
- [LikeC4 Documentation](https://likec4.dev/)
- [Taskfile Documentation](https://taskfile.dev/)
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)

**Project-specific guides:**
- [README-documentor.md](./README-documentor.md) - Content contributor guide
- [TESTING.md](./TESTING.md) - Detailed testing documentation
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for documentors

## 🤝 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:
```bash
task build
```

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