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 technicalWriter 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
   ```

3. **If using Devbox**, enter the Devbox shell:

   ```bash
   devbox shell
   ```
   
   This ensures all tools (Hugo, Node.js, Go) are available in the correct versions.

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

   Example: Create a simple view in `resources/edp-likec4/views/my-view.c4`:

   ```likec4
   specification {
     element myperson
     element mysystem
   }
   
   model {
     customer = myperson 'Customer' {
       description 'End user of the platform'
     }
     
     mySystem = mysystem 'My System' {
       description 'Example system component'
     }
     
     customer -> mySystem 'uses'
   }
   
   views {
     view myCustomView {
       title "My Custom Architecture View"
       
       include customer
       include mySystem
       
       autoLayout TopBottom
     }
   }
   ```

3. **Regenerate webcomponents:**

   ```bash
   task likec4:generate
   ```

4. **Embed diagrams in Markdown:**

   ```markdown
   {{</* likec4-view view="myCustomView" project="architecture" title="My Custom Architecture View" */>}}
   ```

   **Finding available view IDs:**
   - Open the `.c4` files in your project directory
   - Look for `view <viewId> {` declarations
   - The `<viewId>` is what you use in the `view` parameter
   - Or use: `grep -r "^view " resources/edp-likec4/ --include="*.c4"`

## 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 Technical Writers

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/)