website-and-documentation/README.md

# IPCEI-CIS Developer Framework Documentation

[![Built with Hugo](https://img.shields.io/badge/Built%20with-Hugo-pink.svg)](https://gohugo.io/)
[![Styled with Docsy](https://img.shields.io/badge/Styled%20with-Docsy-blue.svg)](https://www.docsy.dev/)
[![Architecture with LikeC4](https://img.shields.io/badge/Architecture-LikeC4-purple.svg)](https://likec4.dev/)

This repository contains the comprehensive documentation for the IPCEI-CIS Developer Framework, including:

- 🏗️ **Architecture Documentation** - Interactive C4 diagrams and system design
- 📖 **User Guides** - How to use and develop with the platform
- 📝 **ADRs** - Architecture Decision Records
- 🚀 **Platform Features** - Component documentation and guides

## Quick Start

### For Technical Writers (Content Writers)

If you want to contribute to the documentation, see **[README-technicalWriter.md](./README-technicalWriter.md)** for detailed instructions.

**Quick start:**

```bash
# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework

# Install dependencies
task deps:install

# If using Devbox
devbox shell

# Start development server
task serve

# Open browser at http://localhost:1313
```

### For Readers

The documentation is published at:
- **Production**: `https://<production-url>`
- **Development**: `https://<dev-url>`

## Project Structure

```
.
├── content/              # Documentation content (Markdown)
│   └── en/
│       ├── docs/        # Main documentation
│       │   ├── architecture/  # Architecture docs with LikeC4
│       │   ├── documentation/ # Technical Writer guides
│       │   └── v1/           # Legacy documentation
│       └── blog/        # Blog posts
├── resources/           # LikeC4 architecture models
│   ├── edp-likec4/     # Platform architecture
│   └── doc-likec4/     # Documentation platform architecture
├── layouts/            # Hugo templates & shortcodes
├── assets/             # SCSS, fonts, images
├── static/             # Static files (JS, CSS, images)
├── Taskfile.yml        # Task automation
└── devbox.json         # Devbox environment definition
```

## Technology Stack

- **[Hugo](https://gohugo.io/)** - Static site generator
- **[Docsy](https://www.docsy.dev/)** - Documentation theme
- **[LikeC4](https://likec4.dev/)** - Interactive architecture diagrams
- **[Task](https://taskfile.dev/)** - Task runner
- **[Devbox](https://www.jetify.com/devbox/)** - Development environment

## Available Tasks

View all tasks:
```bash
task --list
```

Common tasks:
- `task serve` - Start development server
- `task build` - Build production site
- `task test` - Run all tests
- `task likec4:generate` - Generate LikeC4 webcomponents
- `task likec4:validate` - Validate LikeC4 models

## Development Environments

### Option 1: Devbox (Recommended)

[Devbox](https://www.jetify.com/devbox/) provides an isolated, reproducible environment:

```bash
# Install Devbox (if not already installed)
curl -fsSL https://get.jetify.com/devbox | bash

# Enter the shell
devbox shell

# All tools are now available in correct versions
hugo version
node --version
```

### Option 2: VS Code Dev Container

The `.devcontainer` folder contains the configuration for a containerized development environment:

1. Open in VS Code
2. Press `F1` → "Reopen in Container"
3. Wait for container to build
4. Development server starts automatically

### Option 3: Manual Installation

Install the following tools:
- Hugo Extended (v0.151.0+)
- Node.js (v24+)
- Go (for htmltest)
- Task (task runner)

## Contributing

We welcome contributions! Please:

1. Read [README-technicalWriter.md](./README-technicalWriter.md) for documentation guidelines
2. Check existing [ADRs](./content/en/docs/decisions/) for architectural context
3. Create a branch for your changes
4. Run `task test` before committing
5. Submit a pull request

## Documentation Guidelines

- **Write in present tense** - "The system processes..." not "will process"
- **Use architecture diagrams** - LikeC4 for interactive diagrams
- **Keep it concise** - Readers appreciate brevity
- **Test locally** - Run `task serve` and verify changes
- **Update regularly** - Stale docs are worse than no docs

## License

[License information here]

## Support

- **Issues**: [Issue Tracker](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation/issues)
- **Discussions**: [Forum/Chat Link]
- **Documentation**: This repository

---

For detailed documentation contribution guidelines, see [README-technicalWriter.md](./README-technicalWriter.md).