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

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

#### 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
├── 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

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

## 🧪 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/)
- [Taskfile Documentation](https://taskfile.dev/)
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)

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