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. 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

📚 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.)

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

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
├── layouts/           # Custom HTML templates
├── static/            # Static files
├── assets/            # Assets (SCSS, images)
├── public/            # Generated site (not in Git)
├── resources/         # Hugo cache (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

📝 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 */>}}

🧪 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
• Taskfile Documentation
• Devbox Documentation

🤝 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.