website-and-documentation/README.md

IPCEI-CIS Developer Framework Documentation

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 Documentors (Content Writers)

If you want to contribute to the documentation, see README-documentor.md for detailed instructions.

Quick start:

# 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/ # Documentor 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 - Static site generator
• Docsy - Documentation theme
• LikeC4 - Interactive architecture diagrams
• Task - Task runner
• Devbox - Development environment

Available Tasks

View all tasks:

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 provides an isolated, reproducible environment:

# 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-documentor.md for documentation guidelines
2. Check existing ADRs 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
• Discussions: [Forum/Chat Link]
• Documentation: This repository

---

For detailed documentation contribution guidelines, see README-documentor.md.