website-and-documentation/content/en/docs/documentation/local-development.md

---
title: "Local Development"
linkTitle: "Local Development"
weight: 20
description: >
  Set up your local environment and learn the documentor workflow.
---

## Prerequisites

Before you start, ensure you have:

- **Devbox** or the following tools installed:
  - Hugo Extended (latest version)
  - Node.js (v24+)
  - Go (for htmltest)
  - Git

## Installation

1. Clone the repository:

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

2. Install dependencies:

   ```bash
   task deps:install
   ```

## Local Development Workflow

{{< likec4-view view="localDevelopment" project="documentation-platform" >}}

### Starting the Development Server

The easiest way to work locally is to start the Hugo development server:

```bash
task serve
```

This will:

- Generate build information (git commit, version)
- Start Hugo server on `http://localhost:1313`
- Enable hot reload - changes appear instantly in the browser

### Content Structure

```text
content/
└── en/                      # English content
    ├── _index.md           # Homepage
    ├── blog/               # Blog posts
    └── docs/               # Documentation
        ├── architecture/   # Architecture docs
        ├── decisions/      # ADRs
        └── v1/            # Version-specific docs
```

### Creating Content

1. **Add a new documentation page:**

   ```bash
   # Create a new markdown file
   vim content/en/docs/your-topic/_index.md
   ```

2. **Add frontmatter:**

   ```yaml
   ---
   title: "Your Topic"
   linkTitle: "Your Topic"
   weight: 10
   description: >
     Brief description of your topic.
   ---
   ```

3. **Write your content** in Markdown

4. **Preview changes** - they appear immediately if `task serve` is running

### Creating Architecture Diagrams

Architecture diagrams are created with LikeC4:

1. **Navigate to the appropriate LikeC4 project:**
   - `resources/edp-likec4/` - Platform architecture
   - `resources/doc-likec4/` - Documentation platform architecture

2. **Edit or create `.c4` files** with your model

3. **Regenerate webcomponents:**

   ```bash
   task likec4:generate
   ```

4. **Embed diagrams in Markdown:**

   ```markdown
   {{< likec4-view view="localDevelopment" title="Local Development Workflow" >}}
   ```

   Available views:
   - `overview` - Complete system overview
   - `localDevelopment` - Documentor workflow
   - `cicdPipeline` - CI/CD process
   - `deploymentFlow` - Edge deployment
   - `fullWorkflow` - End-to-end workflow
   - `testingCapabilities` - Testing overview

## Available Tasks

View all available tasks:

```bash
task --list
```

### Common Development Tasks

| Task | Description |
|------|-------------|
| `task serve` | Start development server with hot reload |
| `task build` | Build production-ready site |
| `task build:dev` | Build development version |
| `task clean` | Remove build artifacts |
| `task test` | Run all tests |
| `task test:quick` | Run tests without link checking |

## Quick Testing

Before committing, run quick tests:

```bash
task test:quick
```

This validates:

- Hugo build succeeds
- Markdown syntax is correct

For comprehensive testing, including link checking:

```bash
task test
```

## Tips for Documentors

1. **Write in present tense** - "The system processes..." not "The system will process..."
2. **Use code blocks** with syntax highlighting
3. **Include diagrams** for complex concepts
4. **Test locally** before pushing
5. **Keep it concise** - readers appreciate brevity
6. **Update regularly** - stale docs are worse than no docs

## Troubleshooting

### Port 1313 already in use

```bash
# Find and kill the process
lsof -ti:1313 | xargs kill -9
```

### Build errors

```bash
# Clean and rebuild
task clean
task build:dev
```

### Missing dependencies

```bash
# Reinstall all dependencies
task deps:install
```

## Next Steps

Now that you can develop locally, learn about:

- [Testing processes](../testing/)
- [CI/CD pipeline](../cicd/)